@stim-cli/server 1.23.1 → 1.25.0

package/README.md

@@ -49,8 +49,8 @@ and [device-host clients](#device-host-approval). The plain listing shows
 [Actions](#actions).
 
 `GET http://127.0.0.1:7787/health` answers requests from this machine with the
-server's name, versions, `stimBuild` (the digest of the bundled Stim's build,
-which offload compares between machines), protocol, `stimHome`, `startup`, `busy`
+server's name, versions, `stimBuild` (the digest of the bundled Stim's build),
+protocol, `stimHome`, `startup`, `busy`
 (the offloaded `builds` and `hostedSessions` running now) and the current
 Tailscale state. It answers HTTP 200 once `startup.state` is `ready`; while the
 state is `pending` or `degraded` (see the LaunchAgent notes below) it answers
@@ -547,8 +547,11 @@ are not carried over: phones pair again, and remote machines are approved
 again with a new setup ticket.
 
 Stim Desktop and other clients of the server's own user on the same machine do
-not pair. They connect to the Unix socket `$STIM_HOME/server/local.sock`, mode
-0600 in a 0700 directory, which serves only this user and needs no handshake.
+not pair. They connect to the Unix socket `$STIM_HOME/server/local.sock`. If
+that path exceeds the platform's limit (103 UTF-8 bytes on macOS, 107 on Linux), the socket instead lives at
+`/tmp/stim-sockets-<uid>/<sha256-of-normalized-socket-path>.sock`, so long hosted
+session homes remain usable and distinct homes keep distinct sockets. The
+socket is mode 0600 in a mode 0700 directory owned by this user and needs no handshake.
 That connection gets read and control. The Desktop-only methods (`route.setup`,
 `machines.update.*`, `device-host.sessions` and `device-host.sessions.stop`)
 work only there; on a server Desktop started, only after the private Desktop
@@ -556,8 +559,13 @@ bootstrap proof (see [Private Desktop bootstrap](#private-desktop-bootstrap)).
 Windows has no socket.
 
 The network address, `tailscale whois` and the `X-Forwarded-For` header that
-`tailscale serve` adds never authenticate. They only label a record (`from` in
-`stim-server devices`) and key the rate limits below.
+`tailscale serve` adds never authenticate. They label a record (`from` in
+`stim-server devices`) and key the rate limits below. Tailscale rewrites the
+header to the real tailnet source, so remote clients cannot forge it. A local
+process on the host can connect to the loopback port and forge it to lock one
+named peer, or the shared local bucket, out for the lockout window. It
+authenticates nothing and reads nothing. This is accepted because it needs
+local code execution on the host.
 
 A connection must finish the handshake and send `hello` within 5 seconds of
 each step. Five failed attempts from the same peer address within a minute
@@ -1143,6 +1151,12 @@ stream over WireGuard with socket backpressure; no public tunnel, Funnel or
 Tailscale serve configuration change is needed. The 64 KiB server message
 limit remains unchanged.
 
+An approved client calls `device-host.metro.ports` with `{ports}`, at most 256
+of them, before it starts Metro for an iOS Expo dev client, and the host
+answers `{busy}`: the listed ports that already accept loopback connections,
+apart from the client's own dev-client bridges. The feature
+`hosted-metro-ports` advertises it.
+
 Replaying the same open request keeps the port. Client disconnection leaves
 the bridge available for the same session while its server owner lives. Call
 `device-host.metro.close` to replace a gateway, then reopen on the same port;
@@ -1601,6 +1615,8 @@ connected since stim-server started keeps its directory when revoked.
   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;
+  `compat`, the bundled Stim's build compatibility version, which a client
+  compares instead of `stimBuild` when it is present;
   `os`, the OS stim-server runs on as Node names it (`darwin`, `linux`, `win32`);
   `arch`; `xcode`; `simulatorSdk`; `macosSdk` (from
   `xcrun --sdk macosx --show-sdk-version`); `cocoapods`; `runtimes`, the simulator
@@ -1638,8 +1654,10 @@ connected since stim-server started keeps its directory when revoked.
   architecture and target options. These are exact lookups, not a full inventory.
   With `react-native-peer-cache`, a React Native/Expo development offer can send
   `reactNativeArtifact: { project, fingerprint, isExpo, platform, toolchain, ios | android }`.
-  The query includes the caller's compatible toolchain and normalized native
-  build choices; the worker constructs its own receipt around compilation.
+  The query includes the caller's compatible toolchain, whose `toolchain.compat`
+  takes the place of `stimBuild` with `build-compat`, and normalized native
+  build choices; a caller sends React Native and SwiftPM queries only to a
+  server with `build-compat`; the worker constructs its own receipt around compilation.
   The returned identity is opaque, not an alias for the caller's local cache key.
   The completed receipt binds the worker-verified post-mutation fingerprint
   and native options to the toolchain checked before and after compilation.
@@ -1647,7 +1665,7 @@ connected since stim-server started keeps its directory when revoked.
   does not discard a matching archive. Older workers receive no new query
   parameters and continue through their normal build path.
   With `swiftpm-peer-cache`, `swiftpmArtifact` carries `project`, `sourceDigest`,
-  `stimBuild`, complete `inputs` (`ignored`, `outputs`, `localFiles`,
+  `stimBuild` or, with `build-compat`, `compat` in its place, complete `inputs` (`ignored`, `outputs`, `localFiles`,
   `environment`) and `build` (`product`, `infoPlist`, `resources`, `assetCatalog`).
   Resource and catalog paths are repository-relative; the plist is
   project-relative. The worker verifies actual transferred files and full
@@ -1697,14 +1715,25 @@ 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`) and `stimBuild`, after the whole manifest of `repo` was
+  `ccache` or `none`), `stimBuild` and, from a caller that saw `build-compat`, `compat`, 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. It returns `{ "job" }`. It fails with
+  write and remote policies allow it. With the `fingerprint-sources` feature, a
+  caller can send `fingerprintSources`, the `id` and `hash` of each source of
+  `fingerprint`, and a `fingerprint-mismatch` failure names the sources that
+  differ and the synced files prebuild or `pod install` rewrote. With the
+  `fingerprint-ignored` feature, it can send `fingerprintIgnored`, the paths
+  relative to `project` that its git ignores for `fingerprint` through
+  `.git/info/exclude` or a global excludes file, which the machine's synced
+  checkout has no copy of. With the `fingerprint-tracked` feature, it can
+  send `fingerprintTracked`, the top-level entry names of `project` that its
+  git tracks although an ignore pattern matches them, which the machine's
+  empty index would skip. It returns `{ "job" }`. It fails with
   `build-busy` while the offer would be declined, naming the reason, or while
   another build of the same client and repository runs, or while every one
   of this machine's `concurrency.maxBuilds` slots is held, and with
-  `build-refused` when `stimBuild` differs. The build runs `offload-worker.mjs` of the bundled Stim with
+  `build-refused` when `compat` differs from this machine's, or, when either
+  side has no `compat`, when `stimBuild` differs. The build runs `offload-worker.mjs` of the bundled Stim with
   `STIM_HOME` set to the repository's area. It makes the area's checkout
   hold exactly the manifest (a file git lists as untracked and not ignored,
   and not in the manifest, is deleted; ignored dependencies and generated
@@ -2497,7 +2526,6 @@ silent only when every notification it sums up is. An older server ignores
 `levels` and alerts for every event but `started`.
 
 The server and phone import the same pure rules from `@stim-cli/core/oversight`.
-The phone formats home attention messages locally from the facts the shared rule selects.
 `__tests__/oversight-agreement.test.ts` checks their categories, workspace names
 and needs-attention vectors. Notification delivery remains local to each.
 

package/dist/{protocol-BKpAsa9G.mjs → protocol-VEZO2CyR.mjs}

@@ -290,15 +290,21 @@ const swiftpmArtifactInputs = {
 		}
 	}
 };
+const buildCompat = {
+	type: "integer",
+	minimum: 1,
+	description: "The Stim build compatibility version, sent to a stim-server with the build-compat feature."
+};
+const stimIdentity = [{ required: ["stimBuild"] }, { required: ["compat"] }];
 const swiftpmArtifactQuery = {
 	type: "object",
 	required: [
 		"project",
 		"sourceDigest",
-		"stimBuild",
 		"inputs",
 		"build"
 	],
+	oneOf: stimIdentity,
 	additionalProperties: false,
 	properties: {
 		project: { type: "string" },
@@ -308,6 +314,7 @@ const swiftpmArtifactQuery = {
 			minLength: 1,
 			maxLength: 256
 		},
+		compat: buildCompat,
 		inputs: swiftpmArtifactInputs,
 		build: {
 			type: "object",
@@ -379,13 +386,14 @@ const reactNativeArtifactQuery = {
 		platform: { enum: ["ios", "android"] },
 		toolchain: {
 			type: "object",
-			required: ["stimBuild"],
+			oneOf: stimIdentity,
 			additionalProperties: false,
 			properties: {
 				stimBuild: {
 					type: "string",
 					minLength: 1
 				},
+				compat: buildCompat,
 				arch: {
 					type: "string",
 					minLength: 1
@@ -2275,6 +2283,20 @@ function protocolJsonSchema() {
 						pattern: "^[a-f0-9]{64}$"
 					}
 				}, ["gatewayPort", "secret"])),
+				request("device-host.metro.ports", {
+					type: "object",
+					required: ["ports"],
+					additionalProperties: false,
+					properties: { ports: {
+						type: "array",
+						maxItems: 256,
+						items: {
+							type: "integer",
+							minimum: 1,
+							maximum: 65535
+						}
+					} }
+				}),
 				request("device-host.metro.close", session({})),
 				request("device-host.frames.subscribe", session({
 					fps: {
@@ -3106,6 +3128,48 @@ function protocolJsonSchema() {
 							type: ["string", "null"],
 							minLength: 1
 						},
+						fingerprintSources: {
+							type: "array",
+							maxItems: 2e4,
+							description: "The id and hash of each source of fingerprint, to name the sources that differ.",
+							items: {
+								type: "object",
+								required: ["id", "hash"],
+								additionalProperties: false,
+								properties: {
+									id: {
+										type: "string",
+										minLength: 1,
+										maxLength: 1024
+									},
+									hash: {
+										type: ["string", "null"],
+										pattern: "^[0-9a-f]{1,128}$"
+									}
+								}
+							}
+						},
+						fingerprintIgnored: {
+							type: "array",
+							maxItems: 2e4,
+							description: "Paths relative to project that git ignores for fingerprint on the caller, such as through .git/info/exclude.",
+							items: {
+								type: "string",
+								minLength: 1,
+								maxLength: 1024
+							}
+						},
+						fingerprintTracked: {
+							type: "array",
+							maxItems: 2e4,
+							description: "Top-level entries of project that the caller git tracks for fingerprint although an ignore pattern matches them.",
+							items: {
+								type: "string",
+								minLength: 1,
+								maxLength: 255,
+								pattern: "^[^/\\u0000]+$"
+							}
+						},
 						native: { oneOf: [{
 							type: "object",
 							required: [
@@ -3248,6 +3312,10 @@ function protocolJsonSchema() {
 						stimBuild: {
 							type: "string",
 							minLength: 1
+						},
+						compat: {
+							...buildCompat,
+							description: "Compared instead of stimBuild by a machine whose build.offer toolchain reports compat."
 						}
 					}
 				}),

package/dist/protocol.mjs

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

package/dist/protocol.schema.json

@@ -1271,11 +1271,16 @@
               "native-gradle-artifact-cache",
               "native-gradle-peer-cache",
               "react-native-peer-cache",
+              "fingerprint-sources",
+              "fingerprint-ignored",
+              "fingerprint-tracked",
               "swiftpm-peer-cache",
               "build-dependency-cache",
               "hosted-android-data",
               "hosted-android-process",
+              "hosted-metro-ports",
               "server-update",
+              "build-compat",
               "status-views",
               "desktop-reports",
               "desktop-report-platform",
@@ -3183,6 +3188,44 @@
             }
           }
         },
+        {
+          "type": "object",
+          "required": [
+            "id",
+            "method",
+            "params"
+          ],
+          "additionalProperties": false,
+          "properties": {
+            "id": {
+              "type": [
+                "integer",
+                "string"
+              ]
+            },
+            "method": {
+              "const": "device-host.metro.ports"
+            },
+            "params": {
+              "type": "object",
+              "required": [
+                "ports"
+              ],
+              "additionalProperties": false,
+              "properties": {
+                "ports": {
+                  "type": "array",
+                  "maxItems": 256,
+                  "items": {
+                    "type": "integer",
+                    "minimum": 1,
+                    "maximum": 65535
+                  }
+                }
+              }
+            }
+          }
+        },
         {
           "type": "object",
           "required": [
@@ -6843,8 +6886,17 @@
                     },
                     "toolchain": {
                       "type": "object",
-                      "required": [
-                        "stimBuild"
+                      "oneOf": [
+                        {
+                          "required": [
+                            "stimBuild"
+                          ]
+                        },
+                        {
+                          "required": [
+                            "compat"
+                          ]
+                        }
                       ],
                       "additionalProperties": false,
                       "properties": {
@@ -6852,6 +6904,11 @@
                           "type": "string",
                           "minLength": 1
                         },
+                        "compat": {
+                          "type": "integer",
+                          "minimum": 1,
+                          "description": "The Stim build compatibility version, sent to a stim-server with the build-compat feature."
+                        },
                         "arch": {
                           "type": "string",
                           "minLength": 1
@@ -6988,10 +7045,21 @@
                   "required": [
                     "project",
                     "sourceDigest",
-                    "stimBuild",
                     "inputs",
                     "build"
                   ],
+                  "oneOf": [
+                    {
+                      "required": [
+                        "stimBuild"
+                      ]
+                    },
+                    {
+                      "required": [
+                        "compat"
+                      ]
+                    }
+                  ],
                   "additionalProperties": false,
                   "properties": {
                     "project": {
@@ -7006,6 +7074,11 @@
                       "minLength": 1,
                       "maxLength": 256
                     },
+                    "compat": {
+                      "type": "integer",
+                      "minimum": 1,
+                      "description": "The Stim build compatibility version, sent to a stim-server with the build-compat feature."
+                    },
                     "inputs": {
                       "type": "object",
                       "required": [
@@ -7303,6 +7376,54 @@
                   ],
                   "minLength": 1
                 },
+                "fingerprintSources": {
+                  "type": "array",
+                  "maxItems": 20000,
+                  "description": "The id and hash of each source of fingerprint, to name the sources that differ.",
+                  "items": {
+                    "type": "object",
+                    "required": [
+                      "id",
+                      "hash"
+                    ],
+                    "additionalProperties": false,
+                    "properties": {
+                      "id": {
+                        "type": "string",
+                        "minLength": 1,
+                        "maxLength": 1024
+                      },
+                      "hash": {
+                        "type": [
+                          "string",
+                          "null"
+                        ],
+                        "pattern": "^[0-9a-f]{1,128}$"
+                      }
+                    }
+                  }
+                },
+                "fingerprintIgnored": {
+                  "type": "array",
+                  "maxItems": 20000,
+                  "description": "Paths relative to project that git ignores for fingerprint on the caller, such as through .git/info/exclude.",
+                  "items": {
+                    "type": "string",
+                    "minLength": 1,
+                    "maxLength": 1024
+                  }
+                },
+                "fingerprintTracked": {
+                  "type": "array",
+                  "maxItems": 20000,
+                  "description": "Top-level entries of project that the caller git tracks for fingerprint although an ignore pattern matches them.",
+                  "items": {
+                    "type": "string",
+                    "minLength": 1,
+                    "maxLength": 255,
+                    "pattern": "^[^/\\u0000]+$"
+                  }
+                },
                 "native": {
                   "oneOf": [
                     {
@@ -7562,6 +7683,11 @@
                 "stimBuild": {
                   "type": "string",
                   "minLength": 1
+                },
+                "compat": {
+                  "type": "integer",
+                  "minimum": 1,
+                  "description": "Compared instead of stimBuild by a machine whose build.offer toolchain reports compat."
                 }
               }
             }
@@ -7844,8 +7970,17 @@
                     },
                     "toolchain": {
                       "type": "object",
-                      "required": [
-                        "stimBuild"
+                      "oneOf": [
+                        {
+                          "required": [
+                            "stimBuild"
+                          ]
+                        },
+                        {
+                          "required": [
+                            "compat"
+                          ]
+                        }
                       ],
                       "additionalProperties": false,
                       "properties": {
@@ -7853,6 +7988,11 @@
                           "type": "string",
                           "minLength": 1
                         },
+                        "compat": {
+                          "type": "integer",
+                          "minimum": 1,
+                          "description": "The Stim build compatibility version, sent to a stim-server with the build-compat feature."
+                        },
                         "arch": {
                           "type": "string",
                           "minLength": 1
@@ -7989,10 +8129,21 @@
                   "required": [
                     "project",
                     "sourceDigest",
-                    "stimBuild",
                     "inputs",
                     "build"
                   ],
+                  "oneOf": [
+                    {
+                      "required": [
+                        "stimBuild"
+                      ]
+                    },
+                    {
+                      "required": [
+                        "compat"
+                      ]
+                    }
+                  ],
                   "additionalProperties": false,
                   "properties": {
                     "project": {
@@ -8007,6 +8158,11 @@
                       "minLength": 1,
                       "maxLength": 256
                     },
+                    "compat": {
+                      "type": "integer",
+                      "minimum": 1,
+                      "description": "The Stim build compatibility version, sent to a stim-server with the build-compat feature."
+                    },
                     "inputs": {
                       "type": "object",
                       "required": [

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

@@ -1,4 +1,4 @@
-import { n as protocol_exports } from "./protocol-BKpAsa9G.mjs";
+import { n as protocol_exports } from "./protocol-VEZO2CyR.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";
@@ -3226,6 +3226,32 @@ function validFile(file) {
 const validRepo = (repo) => typeof repo === "string" && new RegExp(protocol_exports.BUILD_REPO_PATTERN).test(repo);
 const gb = (bytes) => (bytes / 1024 ** 3).toFixed(1);
 const optional = (value) => typeof value === "string" ? value : null;
+const MAX_FINGERPRINT_SOURCES = 2e4;
+function fingerprintSources(value) {
+	if (value === void 0) return void 0;
+	if (!Array.isArray(value) || value.length > MAX_FINGERPRINT_SOURCES) return null;
+	return value.every((source) => isJsonObject(source) && Object.keys(source).every((key) => key === "id" || key === "hash") && typeof source.id === "string" && source.id.length > 0 && source.id.length <= MAX_PATH_CHARS && (source.hash === null || typeof source.hash === "string" && /^[0-9a-f]{1,128}$/.test(source.hash))) ? value : null;
+}
+function fingerprintIgnored(value) {
+	if (value === void 0) return void 0;
+	if (!Array.isArray(value) || value.length > MAX_FINGERPRINT_SOURCES) return null;
+	const paths = [];
+	for (const path of value) {
+		if (typeof path !== "string" || path.length === 0 || path.length > MAX_PATH_CHARS) return null;
+		paths.push(path);
+	}
+	return paths;
+}
+function fingerprintTracked(value) {
+	if (value === void 0) return void 0;
+	if (!Array.isArray(value) || value.length > MAX_FINGERPRINT_SOURCES) return null;
+	const names = [];
+	for (const name of value) {
+		if (!(typeof name === "string" && name.length > 0 && name.length <= 255 && name !== "." && name !== ".." && !/[/\0]/.test(name))) return null;
+		names.push(name);
+	}
+	return names;
+}
 const GRADLE_NAME = /^[A-Za-z0-9_-]{1,100}$/;
 const GRADLE_ROOT = /^[A-Za-z0-9._/ -]{1,200}$/;
 const GRADLE_MODULE = /^(:(?!\.\.?(?::|$))[A-Za-z0-9._-]+){1,20}$/;
@@ -3257,7 +3283,7 @@ function macosBuildOptions(params) {
 	const artifactQuery = options.artifactInputs === void 0 ? null : swiftpmArtifactQuery({
 		project: params.project,
 		sourceDigest: params.fingerprint,
-		stimBuild: params.stimBuild,
+		...typeof params.compat === "number" ? { compat: params.compat } : { stimBuild: params.stimBuild },
 		inputs: options.artifactInputs,
 		build: {
 			product: options.product,
@@ -3522,7 +3548,7 @@ var BuildHost = class {
 			},
 			warm: {
 				checkout: existsSync(join(area, "src")),
-				dependencies: typeof params.lockfile === "string" && dependencies !== void 0 && reusableDependencies(area, dependencies.project, dependencies.packageName, params.lockfile, this.options.env),
+				dependencies: typeof params.lockfile === "string" && dependencies !== void 0 && reusableDependencies(area, dependencies.project, params.lockfile, this.options.env),
 				build: false
 			},
 			...artifact !== void 0 ? { artifact } : {}
@@ -3610,7 +3636,7 @@ var BuildHost = class {
 		const query = swiftpmArtifactQuery({
 			project: job.project,
 			sourceDigest: job.expectedFingerprint,
-			stimBuild: job.stimBuild,
+			...typeof job.compat === "number" ? { compat: job.compat } : { stimBuild: job.stimBuild },
 			inputs: options.artifactInputs,
 			build: {
 				product: options.product,
@@ -4305,7 +4331,13 @@ var BuildSession = class {
 			native = input;
 		}
 		if (native?.provider !== "gradle" && (typeof params.fingerprint !== "string" || !params.fingerprint)) return refusal("bad-request", "build.start needs params.fingerprint.");
+		const expectedSources = fingerprintSources(params.fingerprintSources);
+		if (expectedSources === null) return refusal("bad-request", `params.fingerprintSources must be at most ${MAX_FINGERPRINT_SOURCES} sources, each an id and a hex hash or null.`);
 		if (!native && [...this.files.values()].some((file) => file.kind === "directory")) return refusal("bad-request", "Directory entries require a native build request.");
+		const expectedIgnored = fingerprintIgnored(params.fingerprintIgnored);
+		if (expectedIgnored === null) return refusal("bad-request", `params.fingerprintIgnored must be at most ${MAX_FINGERPRINT_SOURCES} paths of at most ${MAX_PATH_CHARS} characters.`);
+		const expectedTracked = fingerprintTracked(params.fingerprintTracked);
+		if (expectedTracked === null) return refusal("bad-request", `params.fingerprintTracked must be at most ${MAX_FINGERPRINT_SOURCES} top-level entry names.`);
 		const android = platform === "android" ? androidOptions(params.android) : null;
 		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;
@@ -4320,7 +4352,11 @@ var BuildSession = class {
 		for (const file of this.files.values()) if (!existsSync(this.blobPath(file.sha256))) return refusal("bad-request", `The blob of ${file.path} is missing; sync again.`);
 		const toolchain = await this.host.toolchain(null, native?.provider);
 		if (this.closed) return refusal("build-refused", "The connection closed.");
-		if (!toolchain || toolchain.stimBuild !== params.stimBuild) return refusal("build-refused", `This machine runs Stim build ${toolchain?.stimBuild ?? "unknown"}.`);
+		const compat = typeof params.compat === "number" ? params.compat : void 0;
+		if (!toolchain) return refusal("build-refused", "This machine runs Stim build unknown.");
+		if (compat !== void 0 && toolchain.compat !== void 0) {
+			if (toolchain.compat !== compat) return refusal("build-refused", `This machine runs Stim build ${toolchain.stimBuild ?? "unknown"} with build compatibility ${toolchain.compat}, not ${compat}.`);
+		} else if (toolchain.stimBuild !== params.stimBuild) return refusal("build-refused", `This machine runs Stim build ${toolchain.stimBuild ?? "unknown"}.`);
 		const launched = this.host.launch({
 			client: this.client,
 			repo: params.repo,
@@ -4333,15 +4369,18 @@ var BuildSession = class {
 				android,
 				macos,
 				project: params.project,
-				packageName: optional(params.packageName),
 				isExpo: params.isExpo === true,
 				cacheArtifact: params.cacheArtifact === true,
 				stimBuild: params.stimBuild,
+				...compat !== void 0 && toolchain.compat !== void 0 ? { compat } : {},
 				configuration: optional(params.configuration),
 				scheme: optional(params.scheme),
 				iosProjectPath: optional(params.iosProjectPath),
 				runtime: optional(params.runtime),
 				expectedFingerprint: params.fingerprint,
+				...expectedSources ? { expectedSources } : {},
+				...expectedIgnored ? { expectedIgnored } : {},
+				...expectedTracked ? { expectedTracked } : {},
 				optimizations: isJsonObject(params.optimizations) ? params.optimizations : null
 			}
 		});
@@ -6823,6 +6862,28 @@ function hostedDeviceExclusions(records) {
 		key: hostedDeviceId(record.device)
 	}] : []);
 }
+/** macOS lets 127.0.0.1 bind beside a wildcard listener and takes its loopback traffic, so probe by connecting. */
+function loopbackAccepts(port) {
+	const accepts = (host) => new Promise((resolve) => {
+		const socket = connect({
+			host,
+			port
+		});
+		const done = (open) => {
+			socket.destroy();
+			resolve(open);
+		};
+		socket.setTimeout(1e3, () => done(true));
+		socket.once("connect", () => done(true));
+		socket.once("error", (error) => done(![
+			"ECONNREFUSED",
+			"EADDRNOTAVAIL",
+			"EAFNOSUPPORT",
+			"ENETUNREACH"
+		].includes(error.code ?? "")));
+	});
+	return Promise.all([accepts("127.0.0.1"), accepts("::1")]).then((open) => open.includes(true));
+}
 /** Owns hosted reservations, not build jobs or viewer connections. Native work runs in the packaged CLI child. */
 var DeviceHost = class {
 	owned = /* @__PURE__ */ new Map();
@@ -7190,15 +7251,20 @@ var DeviceHost = class {
 				await this.restoreAndroidMetro(record, owned);
 				return { result: { port } };
 			}
+			const devClientPort = record.platform === "ios" ? params.clientMetroPort : void 0;
 			const bridge = createMetroBridge({
 				peer,
 				gatewayPort: params.gatewayPort,
 				secret: params.secret
 			});
-			const ready = new Promise((resolve, reject) => {
-				bridge.server.once("error", reject);
-				bridge.server.listen(record.metroPort ?? 0, "127.0.0.1", () => resolve(bridge.server.address().port));
-			});
+			const inUse = () => Object.assign(/* @__PURE__ */ new Error(`Port ${devClientPort} is in use on the hosting Mac, and an Expo dev client loads its bundle from the client's Metro port.`), { code: "device-busy" });
+			const ready = (async () => {
+				if (devClientPort !== void 0 && await loopbackAccepts(devClientPort)) throw inUse();
+				return new Promise((resolve, reject) => {
+					bridge.server.once("error", (error) => reject(devClientPort !== void 0 && error.code === "EADDRINUSE" ? inUse() : error));
+					bridge.server.listen(devClientPort ?? record.metroPort ?? 0, "127.0.0.1", () => resolve(bridge.server.address().port));
+				});
+			})();
 			const metro = {
 				bridge,
 				ready,
@@ -7224,7 +7290,7 @@ var DeviceHost = class {
 				throw error;
 			}
 		} catch (error) {
-			return refused$1("action-failed", error.message);
+			return refused$1(error.code === "device-busy" ? "device-busy" : "action-failed", error.message);
 		}
 	}
 	async restoreAndroidMetro(record, owned) {
@@ -7253,6 +7319,24 @@ var DeviceHost = class {
 			if (owned.data === settled) delete owned.data;
 		}
 	}
+	/** Names the ports a new dev-client bridge could not bind, apart from this client's own dev-client bridges. */
+	async metroPorts(client, params) {
+		if (this.closed || !this.options.allowed(client)) return refused$1("forbidden", "Current device-host approval is required.");
+		if (!isJsonObject(params) || !Array.isArray(params.ports) || params.ports.length > 256 || params.ports.some((port) => typeof port !== "number" || !Number.isInteger(port) || port < 1 || port > 65535)) return refused$1("bad-request", "Metro ports needs at most 256 TCP ports.");
+		try {
+			const ports = [...new Set(params.ports)];
+			const sessions = new Set(readHostedSessions().flatMap((record) => record.client === client ? [record.id] : []));
+			const own = new Set([...this.owned].flatMap(([id, { metro }]) => sessions.has(id) && metro?.port !== void 0 && metro.port === metro.clientMetroPort ? [metro.port] : []));
+			const busy = [];
+			const queue = ports.filter((port) => !own.has(port));
+			await Promise.all(Array.from({ length: 16 }, async () => {
+				for (let port = queue.shift(); port !== void 0; port = queue.shift()) if (await loopbackAccepts(port)) busy.push(port);
+			}));
+			return { result: { busy: busy.toSorted((a, b) => a - b) } };
+		} catch (error) {
+			return refused$1("action-failed", error.message);
+		}
+	}
 	async metroClose(client, params) {
 		if (!this.options.allowed(client)) return refused$1("forbidden", "Current device-host approval is required.");
 		if (!isJsonObject(params) || typeof params.session !== "string") return refused$1("bad-request", "Metro close needs a session.");
@@ -16909,7 +16993,7 @@ async function startServer(options) {
 				});
 			}
 			if (method.startsWith("device-host.input.")) return input(id, method.slice(12), raw, session);
-			const answer = method === "device-host.offer" ? await hostedDevices.offer(session.id, raw) : method === "device-host.reserve" ? await hostedDevices.reserve(session.id, raw) : method === "device-host.attach" ? hostedDevices.attach(session.id, raw) : method === "device-host.stop" ? hostedDevices.stop(session.id, raw) : method === "device-host.app.offer" ? hostedDevices.appOffer(session.id, raw) : method === "device-host.app.chunk" ? await hostedDevices.appChunk(session.id, raw) : method === "device-host.app.handoff" ? await hostedDevices.appHandoff(session.id, raw) : method === "device-host.app.launch" ? hostedDevices.appLaunch(session.id, raw) : method === "device-host.app.attach" ? hostedDevices.appAttach(session.id, raw) : method === "device-host.logs.query" ? await hostedDevices.logsQuery(session.id, raw) : method === "device-host.metro.open" ? await hostedDevices.metroOpen(session.id, raw, peer) : await hostedDevices.metroClose(session.id, raw);
+			const answer = method === "device-host.offer" ? await hostedDevices.offer(session.id, raw) : method === "device-host.reserve" ? await hostedDevices.reserve(session.id, raw) : method === "device-host.attach" ? hostedDevices.attach(session.id, raw) : method === "device-host.stop" ? hostedDevices.stop(session.id, raw) : method === "device-host.app.offer" ? hostedDevices.appOffer(session.id, raw) : method === "device-host.app.chunk" ? await hostedDevices.appChunk(session.id, raw) : method === "device-host.app.handoff" ? await hostedDevices.appHandoff(session.id, raw) : method === "device-host.app.launch" ? hostedDevices.appLaunch(session.id, raw) : method === "device-host.app.attach" ? hostedDevices.appAttach(session.id, raw) : method === "device-host.logs.query" ? await hostedDevices.logsQuery(session.id, raw) : method === "device-host.metro.open" ? await hostedDevices.metroOpen(session.id, raw, peer) : method === "device-host.metro.ports" ? await hostedDevices.metroPorts(session.id, raw) : await hostedDevices.metroClose(session.id, raw);
 			return send(socket, "error" in answer ? {
 				id,
 				error: answer.error

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stim-cli/server",
-  "version": "1.23.1",
+  "version": "1.25.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.23.1",
-    "@stim-cli/agent-driver-agent-device": "^1.23.1",
-    "@stim-cli/cache": "^1.23.1",
-    "@stim-cli/core": "^1.23.1",
-    "@stim-cli/transport": "^1.23.1",
-    "@stim-cli/transport-tailscale": "^1.23.1",
-    "stim": "1.23.1",
+    "@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",
     "ws": "^8.21.3"
   },
   "devDependencies": {