stim 1.17.0 → 1.17.1

package/dist/{guide-DjrTQGik.mjs → guide-DC3n6-NH.mjs}

@@ -136,12 +136,12 @@ To learn whether the next build is a cache hit and how long it should take,
 without building, run stim ios --plan (or stim android --plan); see stim guide
 lifecycle builds.
 
-Agents never set STIM_ACCESS_TICKET, run stim-server setup, edit offload.*
-or hosting.* for the user, or approve requests. Read stim guide settings for
+Agents never set STIM_ACCESS_TICKET, run stim-server setup, edit remote.*,
+server.* or hosting.* for the user, or approve requests. Read stim guide settings for
 Desktop access tickets and person-owned approval.
-Read stim guide settings to select a build machine. Keep a requested named
+Read stim guide settings to select a remote Mac. Keep a requested named
 placement when recovering STIM_OFFLOAD_REFUSED: report its reason and remedy.
-When the user mentions slow builds, a busy Mac or wanting updates away from the desk, tell them about Stim Desktop > Settings > Build machines > Add or Phones > Pair a Phone; see stim guide settings.
+When the user mentions slow builds, a busy Mac or wanting updates away from the desk, tell them about Stim Desktop > Settings > Remote Macs > Add or Phones > Pair a Phone; see stim guide settings.
 
 Read stim guide lifecycle concurrency when a build waits on another workspace
 or a build call times out. A native build can outlive a shell timeout; if the
@@ -661,8 +661,8 @@ leased until <time>" for each one.`,
                   looked up", which is a different fact from "nothing was found"
   buildMachine    selected auto, local or machine name, including cache hits
   builtOn         here or machine name when a build ran; absent otherwise
-  offloadedTo     only on an app a build machine compiled: its
-                  offload.machines entry (see \`guide settings\`). cacheHit is
+  offloadedTo     only on an app a remote Mac compiled: its
+                  remote.machines entry (see \`guide settings\`). cacheHit is
                   false for it. The Android payload carries it too
   offloadFallback only on an app compiled here after the run considered
                   offloading it: why it built here -- one reason per
@@ -811,7 +811,7 @@ leased until <time>" for each one.`,
                   sets its own CMake compiler launcher, or a Gradle run whose
                   native work was all up to date. None of the three is an
                   error, and this field is separate from cacheHit. On an
-                  offloaded APK it is the build machine's ccache
+                  offloaded APK it is the remote Mac's ccache
   logs            the workspace log directory
   agentDevice     { stateDir }: absolute workspace agent-device state path
   durationMs      wall time for the whole run
@@ -911,18 +911,18 @@ leased until <time>" for each one.`,
                   android would reclaim, in the \`reclaimed\` shape without
                   freedMb, and is empty while under budget
   deviceHosts     one { machine, state, dnsName?, deviceId?, requestedAt?, host? }
-                  per hosting.machines entry. state is "approved", "pending",
+                  per remote.machines entry. state is "approved", "pending",
                   "not-asked", "revoked", "node-changed", "not-on-tailnet",
                   "tailscale-off", "unreachable", "invalid",
                   "credentials-unavailable" or "busy". Tokens stay private.
                   Only --fix asks for access or forgets removed names.
-                  An approved hosting machine does not imply build approval
-                  or change ios/android placement; see \`guide settings\`.
+                  A remote Mac approved for device hosting does not imply
+                  build approval; see \`guide settings\`.
                   host is { name, screenRecording, accessibility }, present
                   only for approved machines whose worker reports it.
-  buildMachines   one { machine, state, dnsName?, deviceId?, requestedAt?,
+  remoteMachines  one { machine, state, dnsName?, deviceId?, requestedAt?,
                   offloadable?, reasons?, problems?, capacity?, host? } per
-                  offload.machines entry; state is "approved", "pending", "not-asked",
+                  remote.machines entry, for its build approval; state is "approved", "pending", "not-asked",
                   "revoked" (revoked, or the request lapsed), "node-changed",
                   "not-on-tailnet", "tailscale-off", "unreachable" or
                   "invalid". host has the same shape and presence rule as in
@@ -945,7 +945,7 @@ leased until <time>" for each one.`,
                   optional fields
   findings        the diagnostic findings; a lower resolved Stim is a
                   costs-time finding with a PATH or installation remedy
-                  offload-candidate is a note after 3+ successful local cold builds in 7 days average over 3 min, with no offload.machines and an online tailnet Mac; open Stim Desktop Settings > Build machines > Add
+                  offload-candidate is a note after 3+ successful local cold builds in 7 days average over 3 min, with no remote.machines and an online tailnet Mac; open Stim Desktop Settings > Remote Macs > Add
 
 ON FAILURE
   \`start\`, \`ios\`, \`android\` and \`web\` all print the error contract instead,
@@ -1658,8 +1658,8 @@ RULES
              finished request, status "ok" or "failed", durationMs from the
              request to the end of the response
 
-  Each entry of environments also carries build: null, or the ios or android
-  run that holds this workspace's native-run.lock:
+  Each entry of environments also carries build: null, or the ios, android or
+  macos run that holds this workspace's native-run.lock:
 
   build   { platform, slot, state, phase, startedAt, phaseStartedAt,
             outcome, outcomeKnown, cacheLookupOutcome?, expectedMs, expectedPhaseMs,
@@ -1684,6 +1684,11 @@ RULES
                    finishes during the build adds no device time. An
                    --eas-profile run has no cache lookup, so its outcome
                    stays the project's most recent one until install.
+                   A stim macos run enters only prepare, compile (SwiftPM,
+                   with detail), install (staging the bundle, or fetching
+                   it from a build machine) and launch. It has no cache
+                   lookup: outcome is null, plannedPhases is null, and
+                   builds.macos holds its finished runs and their phases.
   startedAt        when the run started; phaseStartedAt when its phase did
   outcome          "cold" after the local/provider lookups resolve a miss;
                    "hit" after a cached artifact is ready to reuse, including
@@ -1733,20 +1738,24 @@ RULES
                    reads: { step, unit, done, total, line, updatedAt }
     step           the tool's step: configure, compile, link, resources,
                    script, dex, package or sign; null before one is known
-    unit           "targets" for xcodebuild, "tasks" for Gradle
+    unit           "targets" for xcodebuild, "tasks" for Gradle, "steps" for
+                   SwiftPM (stim macos)
     done           xcodebuild: targets it finished (a target counts once
                    xcodebuild touches or signs its product, so an
                    incremental build can end below total); Gradle: tasks
-                   it reported so far
+                   it reported so far; SwiftPM: the done of its latest
+                   [done / total] line
     total          xcodebuild: targets in its dependency graph; Gradle: null,
-                   since its plain output gives no total
+                   since its plain output gives no total; SwiftPM: the
+                   total of its latest [done / total] line, which can grow
+                   as SwiftPM plans more of the build
     line           the latest compile, link or task line, paths shortened
                    to file names, at most 160 characters
     updatedAt      when the build last wrote it; the run writes it at most
                    every 2 seconds
   placement        where the build runs: "local", or while it is offloaded
                    { host, phase, startedAt, phaseStartedAt }. host is the
-                   offload.machines entry; phase is the step there: sync,
+                   remote.machines entry; phase is the step there: sync,
                    deps, prebuild, pods, build (xcodebuild or Gradle) or fetch;
                    startedAt is when the offload started and phaseStartedAt
                    when that step did. Meanwhile phase above follows it as
@@ -1800,7 +1809,7 @@ RULES
   lookup, and create no lastBuild record or failed-run stats.
   buildMachine selected auto, local or configured machine entry; always on new build records
   builtOn      here or machine name; absent when no build ran (cache/refusal)
-  offloadedTo  only on a run a build machine compiled: its name
+  offloadedTo  only on a run a remote Mac compiled: its name
   offloadFallback
                only on a run that considered offloading and built here: one
                reason per machine when none took the build, or why the
@@ -1833,7 +1842,7 @@ RULES
   last 10 runs, newest first. Its newest entry that is not "interrupted" is
   the run lastBuilds reports, once a run has recorded builds.
 
-  builds         { ios?, android? }, each a list of lastBuilds entries
+  builds         { ios?, android?, macos? }, each a list of lastBuilds entries
                  with { result, slot, configuration, cacheKey, phases }
   result         "succeeded", "failed", "cancelled" (Stim stopped the run
                  after an interrupt or \`stim stop\`) or "interrupted": its
@@ -2062,7 +2071,7 @@ RULES
   A bucket carries runs, failed, hits, misses, coldRuns, coldRunMs, hitRuns,
   hitRunMs, timeSavedMs, firstRunAt and lastRunAt, plus lastColdBuildMs and
   lastPodsMs once the project has compiled or installed pods, and
-  offloadedRuns, offloadedRunMs and lastOffloadHost once a build machine
+  offloadedRuns, offloadedRunMs and lastOffloadHost once a remote Mac
   compiled one. An offloaded run is a miss but not a cold run, so the cold
   average, time saved and build estimates stay local. Milliseconds are
   integers.
@@ -2181,10 +2190,10 @@ BUILD PLACEMENT (\`offload\`)
   decision, reason, machine?, buildMs?, slotWaitMs?, deviceSlotWaitMs?, localEstimateMs?, failed? }.
   slotWaitMs and deviceSlotWaitMs are whole milliseconds waiting for build
   and owned-device slots respectively, present only when positive.
-  decision is "here", "offloaded", or "fell-back" (it tried a build machine
+  decision is "here", "offloaded", or "fell-back" (it tried a remote Mac
   and built here). reason is why: the run's \`placement:\` reason, such as
   "load 0.6/core, 1 of 3 build slots busy here" (auto keeps the build here
-  while this Mac has room) or "offload.mode is off" (which prints no line),
+  while this Mac has room) or "remote.buildMode is off" (which prints no line),
   or for a fallback the cause, prefixed by the machine it concerns, such as
   "mini: no less loaded (load 1.2/core there, 0.6/core here)". buildMs is the compile here, or the offloaded build's
   total (offer, sync, build and fetch); localEstimateMs is this project's
@@ -2996,7 +3005,7 @@ Branch on the code, never on the message.`,
   logs prints a note on stderr and shows copied records. Update an older stim-server
   on the host to enable handoff and native logs (hello features hosted-ios-data
   for iOS and hosted-android-data for Android).
-  A name outside hosting.machines is STIM_BAD_ARG. Missing or pending hosting
+  A name outside remote.machines is STIM_BAD_ARG. Missing or pending hosting
   approval keeps the doctor --fix and stim-server devices grant remedies.`
 		},
 		STIM_EAS_BUILD_MISSING: {
@@ -3295,10 +3304,10 @@ Branch on the code, never on the message.`,
   works. See stim guide macos.`
 		},
 		STIM_OFFLOAD_REFUSED: {
-			summary: "the selected build machine cannot build this app",
+			summary: "the selected remote Mac cannot build this app",
 			body: () => `STIM_OFFLOAD_REFUSED
 
-A named --build-machine selection is strict. The message names the machine
+A named --remote-build selection is strict. The message names the machine
 and why it cannot take or finish the build: not configured or paired, approval
 pending or denied, unreachable or changed pinned identity, incompatible
 toolchain/runtime/CPU, low disk, busy, sync/build failure, artifact failure,
@@ -3310,12 +3319,12 @@ a build record or failed-run stats. A listed paired name with a cache hit needs
 no build and does not contact the selected machine.
 
 Run stim doctor --fix to ask for build access if not paired. Check
-stim settings get offload.machines. A person on the worker finds the id with
+stim settings get remote.machines. A person on the worker finds the id with
 stim-server devices and approves this Mac with stim-server devices grant <id> --build,
 or runs stim-server setup on the worker with its node, ticket and expiry
 (guide settings). Agents never run setup or approve requests.
-Rerun with --build-machine auto for normal placement and local fallback, or
---build-machine local to keep the build here.
+Rerun with --remote-build auto for normal placement and local fallback, or
+--remote-build local to keep the build here.
 `
 		},
 		STIM_WORKTREE_SERVICE: {
@@ -4799,7 +4808,7 @@ WAITING FOR A CHANGE
 
 If Stim is not installed globally, replace stim with npx stim.
 
-  stim settings set hosting.machines '["janics-mac-mini"]'
+  stim settings set remote.machines '["janics-mac-mini"]'
   stim doctor --fix
   stim doctor
   stim android --remote janics-mac-mini --device-profile pixel_7
@@ -4821,7 +4830,7 @@ Unreadable android.host blocks only its slot; restore its recorded machine and
 session from the host before stopping that slot.
 
 --system-image and --device-profile select installed choices on the host.
-The build targets the offered ABI and --build-machine independently selects a
+The build targets the offered ABI and --remote-build independently selects a
 compatible build worker. Stim builds before reserving, records the session as
 soon as it exists, then delivers one App.apk. The emulator boots headless;
 androidEmulatorApp is ignored with a note.
@@ -4941,7 +4950,7 @@ and show records already copied here.`
 
 If Stim is not installed globally, replace stim with npx stim.
 
-  stim settings set hosting.machines '["janics-mac-mini"]'
+  stim settings set remote.machines '["janics-mac-mini"]'
   stim doctor --fix
   # A person there approves: stim-server devices grant <id> --device-host
   # Or runs stim-server setup on the worker with its client node, ticket and expiry.
@@ -4952,22 +4961,22 @@ If Stim is not installed globally, replace stim with npx stim.
   stim stop
 
 The same setup serves macos --remote. Approval is separate from build, read
-and phone control. Set ios.remote to the machine name for a workspace default;
+and phone control. Set ios.remote to the machine name for a default (machine scope for the whole Mac);
 no flag or setting runs here. eas and proxy keep their remote backend meanings.
 --remote auto (or ios.remote = auto / android.remote = auto) stays here when
 there is a free concurrency.maxDevices slot (0 means unlimited), no device
 waiter ahead, normal host memory pressure, no budget shortfall,
-and 5-minute load per core below offload.maxLoadPerCore. Without hosting.machines,
+and 5-minute load per core below server.maxLoadPerCore. Without remote.machines,
 auto is local. An unknown local device count also stays local; boot admission
 still decides. The default without a flag or setting stays local.
 
-Otherwise Stim asks every approved hosting.machines host in parallel, with a
+Otherwise Stim asks every approved remote.machines host in parallel, with a
 3-second probe timeout and this run's model/runtime or image/profile selectors.
 A compatible choice, no declined reason, normal memory pressure and available
 capacity are required. With a free local slot, a host must report a lower load;
 with a full cap or a queue ahead, an admitted host with unknown load is allowed.
-Hosts rank by the build preference (flag > STIM_OFFLOAD_MACHINE > offload.machine)
-when it names a machine, then lowest load, most free memory and hosting.machines order. Automatic build
+Hosts rank by the build preference (flag > STIM_REMOTE_BUILD > remote.build)
+when it names a machine, then lowest load, most free memory and remote.machines order. Automatic build
 offload resolves later, after the device architecture is known.
 
 When no host admits, auto runs here and may wait in the existing FIFO device
@@ -4990,7 +4999,7 @@ here or elsewhere. --device cannot use a hosting Mac, and --simulator-app
 refuses. The host boots headless and ignores this Mac's iosSimulatorApp setting.
 --slot, --device-type and --runtime select the hosted simulator; --scheme,
 --configuration and --eas-profile select the app as usual. The build targets
-the offered simulator architecture, not this Mac's. --build-machine remains
+the offered simulator architecture, not this Mac's. --remote-build remains
 independent and selects a compatible build worker for a Debug cache miss.
 
 The host's own owned devices count toward concurrency.maxDevices.
@@ -6307,8 +6316,8 @@ OPT-IN CONCURRENCY LIMITS (UNLIMITED BY DEFAULT)
 			summary: "every flag per command, Android variants and flavors, the per-run simulator model, runtime and system image",
 			body: () => `THE OPTION SURFACE, IN FULL
   start           --json --wait <seconds> --remote --reset-cache
-  ios             --build-machine <auto|local|name> --slot <name> --json --plan --no-metro-check --no-build-cache --scheme <name> --configuration <name> --device-type <name> --runtime <version> --simulator-app <xcode|siniulator|stim-desktop> --device [udid] --wait <seconds> --no-wait --remote <eas|proxy|auto|machine>
-  android         --build-machine <auto|local|name> --slot <name> --json --plan --no-metro-check --no-build-cache --variant <name> --system-image <id> --device-profile <id> --device [serial] --wait <seconds> --no-wait --remote <proxy|eas>
+  ios             --remote-build <auto|local|name> --slot <name> --json --plan --no-metro-check --no-build-cache --scheme <name> --configuration <name> --device-type <name> --runtime <version> --simulator-app <xcode|siniulator|stim-desktop> --device [udid] --wait <seconds> --no-wait --remote <eas|proxy|auto|machine>
+  android         --remote-build <auto|local|name> --slot <name> --json --plan --no-metro-check --no-build-cache --variant <name> --system-image <id> --device-profile <id> --device [serial] --wait <seconds> --no-wait --remote <proxy|eas>
   ios/android --wait bounds owned-device slot waits (default 600s), or physical
   leases with --device (default 60s). Remote targets do not join this local
   slot queue. --no-wait refuses a full/queued owned
@@ -7186,7 +7195,10 @@ to stats.json.corrupt-<unix ms> and starts a new one.`,
   stim gc --delete --cache archived-logs        delete logs, keep records
   stim gc --delete --cache archived-recordings  delete recordings, keep records
   stim gc --delete --cache archived-agent       delete agent actions, keep records
-  Per-kind selectors also accept --older-than, measured from removedAt.
+  stim gc --delete --cache archived-logs:<id>   one kind of one archive, keep its record
+  (archived-recordings:<id> and archived-agent:<id> likewise; they ignore --older-than;
+  an unknown id refuses with STIM_BAD_ARG)
+  Per-kind selectors without an id also accept --older-than, measured from removedAt.
   Normal gc, --cache all, --worktrees and unscoped --older-than exclude archives.
   Archive scopes report abandoned staging directories and delete only those
   with no live or unresolved claim. An unresolved claim names its removal command.
@@ -7638,7 +7650,7 @@ THE ONE CASE GC WILL NOT REAP
   check and the stop fails and must be run again, so gc re-checks the build
   locks and the daemon's status right before each stop. Nothing is stopped while an Android build lock, or a build slot no
   iOS build holds, is live or unresolved. stim-server stops the daemons of
-  offloaded builds (offload.gradleDaemonIdleMinutes, \`guide settings\`), so
+  offloaded builds (server.gradleDaemonIdleMinutes, \`guide settings\`), so
   while it runs gc keeps those. A daemon whose home, distribution or status cannot be read is
   kept. Gradle stops an idle daemon itself after 3 hours and Kotlin after 2
   hours by default.
@@ -7900,7 +7912,7 @@ KEYS STIM READS
                         a JS-bundle swap on cache hits. The \`--configuration\`
                         flag overrides this per invocation. Unset means Debug.
   ios.remote            "proxy", "eas", or a named approved Mac from
-                        hosting.machines, with the same meaning as --remote.
+                        remote.machines, with the same meaning as --remote.
                         "auto" places on an approved Mac when this Mac is full or
                         busy. Unset runs here. See lifecycle hosted-ios.
   ios.simslimProfile    a SimSlim JSON profile under the app directory,
@@ -8043,7 +8055,7 @@ ${ANDROID_AVD_CONFIG_HELP.map((line) => `                          ${line}`).joi
                         bare string is used as the literal password. Unset
                         means the debug keystore's fixed "android".
   android.remote        "proxy", "eas", or a named approved Mac in
-                        hosting.machines; "auto" places on an approved Mac when
+                        remote.machines; "auto" places on an approved Mac when
                         this Mac is full or busy. Unset runs here.
                         See lifecycle hosted-android.
   metro.tunnel          selects how a remote device reaches this workspace's
@@ -8368,31 +8380,37 @@ wants a pool says so with the variable.
 DESKTOP ACCESS TICKETS
 Stim Desktop's Add wizard sets STIM_ACCESS_TICKET for one \`doctor --fix\`
 run. Agents never set it, never run \`stim-server setup\`, never edit
-\`offload.*\` or \`hosting.*\` for the user, and never approve requests.
+\`remote.*\`, \`server.*\` or \`hosting.*\` for the user, and never approve requests.
 Stim sends the ticket (43 base64url characters) only in build and device-host access
 requests and stores only its SHA-256 ticketHash. With --fix, a still-pending
 request is replaced when its ticketHash is missing or differs from the current
 ticket; matching hashes and approved credentials are preserved.
-Approved doctor entries under buildMachines and deviceHosts include host
+Approved doctor entries under remoteMachines and deviceHosts include host
 { name, screenRecording, accessibility } when the worker reports it.
 
-BUILD MACHINES AND PHONE APP
+REMOTE MACS AND PHONE APP
 When the user mentions slow builds, a busy Mac, a full disk or device limit, or
 wanting updates away from the desk, tell them about Stim Desktop > Settings >
-Build machines > Add (a Mac on the tailnet that builds or hosts simulators for
+Remote Macs > Add (a Mac on the tailnet that builds or hosts simulators for
 this one) or Phones > Pair a Phone (the Stim phone app). Stim Desktop also
 suggests these itself, at most once a day and never during a build. Agents only
-tell the user: they never run \`stim-server setup\`, never edit \`offload.*\` or
-\`hosting.*\` for the user, and never approve requests.
+tell the user: they never run \`stim-server setup\`, never edit \`remote.*\`,
+\`server.*\` or \`hosting.*\` for the user, and never approve requests.
 
-HOSTING MACHINES ARE MACHINE-LEVEL
-\`hosting.machines\` names Macs that may host owned simulator sessions,
-by MagicDNS name with an optional serve port (default 7443). Name each node
-and port once. This is separate from build offloading:
+REMOTE MACS ARE MACHINE-LEVEL
+\`remote.machines\` names the remote Macs this Mac may build on and host owned
+simulator sessions on, by MagicDNS name with an optional serve port (default
+7443). Name each node and port once:
 
-  stim settings set hosting.machines '["janics-mac-mini"]'
+  stim settings set remote.machines '["janics-mac-mini"]'
   stim doctor --fix
 
+A remote Mac is used for a capability only after it grants that approval. Build
+and device-host approvals are separate: a Mac in the list that never granted
+one is not an error, it is not used for that capability, and doctor reports
+it plainly.
+
+DEVICE HOSTING
 Only \`doctor --fix\` asks for device-host access. A person on that Mac
 approves the printed id with \`stim-server devices grant <id> --device-host\`.
 A person can also run \`stim-server setup\` on the worker: one node, one ticket,
@@ -8404,7 +8422,7 @@ unless every chosen capability already has a matching approval. Desktop reuse
 requires an existing tailnet route. Ctrl-C or SIGTERM completes the journal,
 releases the setup claim and exits 1; a typed N also exits 1. Hosting grants
 include no read, control or build capability.
-On the hosting Mac, Stim Desktop > Settings > Phones > Hosted here lists the
+On a remote Mac that hosts, Stim Desktop > Settings > Phones > Hosted here lists the
 simulators, emulators and apps approved Macs run there, below Device hosting
 approvals. Stop asks for confirmation, ends the session and deletes or parks
 its device on that Mac. Parked sessions remain listed without Stop. The list
@@ -8413,7 +8431,8 @@ support it.
 $STIM_HOME/device-host-machines.json stores a private token and pinned tailnet
 node. Doctor never prints the token; it reports each machine under deviceHosts
 in JSON. Desktop uses placement set by config or agents, such as
-stim settings set ios.remote auto --scope workspace (or android.remote),
+stim settings set ios.remote auto --scope machine (or android.remote; workspace,
+repo and committed scopes override the machine default),
 or per run stim ios --remote auto / stim ios --remote <machine>.
 New Desktop runs pass no --remote flag; recorded hosted sessions keep their
 machine until stim stop. Only devices outside this Mac show "on <machine>"
@@ -8422,19 +8441,19 @@ as hover text.
 Stim sends tokens only to the pinned node's own tailnet address,
 with its MagicDNS name for TLS and Host routing. A changed node refuses
 access, and uncertain replies or unreadable credentials preserve the pin.
-Invalid hosting settings report an error and preserve every saved credential.
-\`doctor --fix\` forgets entries removed from hosting.machines; remove a
+An invalid remote.machines setting reports an error and preserves every saved credential.
+\`doctor --fix\` forgets entries removed from remote.machines; remove a
 replaced machine, run it, then re-add the name to request a new approval.
 A definite revoked or lapsed request can be requested again with --fix.
 An in-progress approval inspection reports busy rather than replacing its
 pending token. \`stim macos --remote <machine>\` runs a macOS app on an
-approved machine (stim guide macos); \`ios\` and \`android\` do not yet
-place sessions on these machines. To view or control a hosted macOS app, a person
+approved remote Mac (stim guide macos); \`ios\` and \`android\` do not yet
+place sessions on these Macs. To view or control a hosted macOS app, a person
 on that Mac approves Screen & System Audio Recording and Device Control and Data
 Access (Accessibility on macOS 26 and earlier) for Stim Host, the app
 \`stim-server service install\` runs the server under.
 
-On a hosting Mac, \`hosting.agentDriver\` names the tool it starts so a
+On a remote Mac that hosts, \`hosting.agentDriver\` names the tool it starts so a
 client's coding agent can drive the macOS apps, iOS simulators and Android emulators it hosts for that client.
 The default, \`none\`, starts nothing. For macOS, \`agent-device\` starts its
 shared daemon only when that agent-device can lease a single app (its
@@ -8448,13 +8467,11 @@ uses one daemon per emulator, pinned by its serial policy, with agent-device
 hosted-ios. \`doctor\` on that Mac notes an installed hosted app that runs while
 the setting is \`none\`.
 
-BUILD MACHINES ARE MACHINE-LEVEL
-\`offload.machines\` lists the Macs on the tailnet that may build for this one,
-by MagicDNS name, each optionally with the port of its \`tailscale serve\`
-route (default 7443):
+REMOTE BUILDS
+The same \`remote.machines\` list names the Macs that may build for this one:
 
   {
-    "offload": { "machines": ["janics-mac-mini"] }
+    "remote": { "machines": ["janics-mac-mini"] }
   }
 
 \`doctor --fix\`, run in any app directory, asks each named Mac for build access and pins its tailnet
@@ -8465,27 +8482,27 @@ ticket and expiry, under the approval rule above. Build never includes read
 or control.
 Stim connects to a named Mac only while its name still belongs to the pinned
 node and never sends the token to another node. \`doctor\` reports each
-machine's pairing state and, for an approved machine, asks it for one build
+remote Mac's build pairing state and, for an approved one, asks it for one build
 offer and lists every reason it would not take this app's iOS build: no
 answer, another Stim build, CPU, Xcode, simulator SDK or CocoaPods, no
 Bundler for an app whose Gemfile.lock pins CocoaPods, no iPhone simulator on
 the runtime \`stim ios\` builds for here, low disk, or busy. With Package.swift
 and no platform selection on a Mac, it also checks the macOS Xcode and SDK.
 
-\`offload.machine\` (machine scope, default auto) selects placement for
-\`ios\`, \`android\` and \`macos\`. \`--build-machine <auto|local|name>\`
-overrides STIM_OFFLOAD_MACHINE, which overrides the setting. A blank environment
+\`remote.build\` (machine scope, default auto) selects placement for
+\`ios\`, \`android\` and \`macos\`. \`--remote-build <auto|local|name>\`
+overrides STIM_REMOTE_BUILD, which overrides the setting. A blank environment
 value is unset. Trimmed auto/local are case-insensitive. Machine names match
 configured names case-insensitively, with port 7443 when omitted; reports use
 the configured entry.
 
-  auto   follows offload.mode and keeps its local fallback behavior
+  auto   follows remote.buildMode and keeps its local fallback behavior
   local  builds only on this Mac for this invocation
-  name   requires a matching entry in offload.machines, already paired and
-         approved; ignores offload.mode and this Mac's load/slot gating
+  name   requires a matching entry in remote.machines, already paired and
+         approved for builds; ignores remote.buildMode and this Mac's load/slot gating
 
-A name never prompts for pairing, tries another machine or falls back here.
-Any refusal or failure is STIM_OFFLOAD_REFUSED with the machine and reason.
+A name never prompts for pairing, tries another remote Mac or falls back here.
+Any refusal or failure is STIM_OFFLOAD_REFUSED with the remote Mac and reason.
 Device, Release/non-Debug, --remote, Android CAS compiler builds, builds with
 the build cache off, and an unknown simulator runtime cannot build there and
 refuse on a cache miss. Invalid values, unlisted names and unpaired names refuse
@@ -8498,39 +8515,39 @@ starts no local xcodebuild, Gradle or SwiftPM compile.
 Run stim doctor --fix to ask for build access if not paired. A person on the
 worker finds the id with stim-server devices and approves it with
 stim-server devices grant <id> --build, or runs stim-server setup there with
-the client node, ticket and expiry. Check stim settings get offload.machines,
-or rerun with --build-machine auto or --build-machine local. Ctrl-C cancels
+the client node, ticket and expiry. Check stim settings get remote.machines,
+or rerun with --remote-build auto or --remote-build local. Ctrl-C cancels
 the remote build without a local xcodebuild, Gradle or SwiftPM compile.
 
 Copyable agent prompt:
-  Run stim ios --build-machine janics-mac-mini. If it refuses, report the
+  Run stim ios --remote-build janics-mac-mini. If it refuses, report the
   STIM_OFFLOAD_REFUSED reason and remedy; do not retry with another placement.
 
-With offload.machine auto, \`offload.mode\` decides where an iOS simulator Debug build or an Android
+With remote.build auto, \`remote.buildMode\` decides where an iOS simulator Debug build or an Android
 emulator debug build or a stim macos SwiftPM Debug build compiles:
 
   auto   (default) here while this Mac has capacity: a free
          \`concurrency.maxBuilds\` slot (always, with no build limit) and a
-         load per core under \`offload.maxLoadPerCore\`. Otherwise on a
-         build machine that accepts the build and is expected to be faster:
-         while every slot here is busy, any machine that accepts; while only
-         the load is high, a machine whose load per core is lower than this
-         Mac's. A machine too old to report its load counts only while every
+         load per core under \`server.maxLoadPerCore\`. Otherwise on a
+         remote Mac that accepts the build and is expected to be faster:
+         while every slot here is busy, any remote Mac that accepts; while only
+         the load is high, one whose load per core is lower than this
+         Mac's. A Mac too old to report its load counts only while every
          slot here is busy.
-  force  on a build machine whenever one accepts it
+  force  on a remote Mac whenever one accepts it
   off    always here
 
 Load per core is the 5-minute load average divided by the CPU count; a Mac's
 native builds are its Stim runs in prebuild, pods or compile on that Mac, not
 the ones it offloaded.
-\`offload.maxLoadPerCore\` (default 2) is also the busy threshold for
+\`server.maxLoadPerCore\` (default 2) is also the busy threshold for
 automatic iOS and Android device placement. It is the load per core at which a Mac
-counts as saturated, both here and on a build machine.
+counts as saturated, both here and on a remote Mac.
 
-STIM_OFFLOAD_MODE overrides it for one command. Device, Release and
+STIM_REMOTE_BUILD_MODE overrides it for one command. Device, Release and
 \`--remote eas|proxy\` builds, Android builds with the Apple Clang CAS compiler cache,
 and iOS/Android runs with the build cache off, always build here. Hosted iOS
-Debug builds can use a separate --build-machine, targeting the hosting Mac's
+Debug builds can use a separate --remote-build, targeting the hosting Mac's
 architecture and runtime.
 macOS uses matching Xcode and macOS SDK, with a per-client SwiftPM dependency
 cache on the worker. It skips JavaScript dependencies, prebuild and pods; see
@@ -8577,27 +8594,27 @@ An offloaded app lands only in this Mac's build cache, not in a remote cache
 provider. A project whose xcodebuild changes its own fingerprinted inputs
 fails the offload fingerprint check: auto builds here; a named placement refuses.
 
-On the build machine, stim-server keeps each client's checkouts, dependencies,
+On a remote Mac that builds for others, stim-server keeps each client's checkouts, dependencies,
 DerivedData, compilation cache, ccache and Gradle home under
-\`offload.workerRoot\` (absolute; default $STIM_HOME/build-worker), one area
+\`server.workerRoot\` (absolute; default $STIM_HOME/build-worker), one area
 and Stim home per client and repository, and one Gradle home per client. It
 runs one offloaded build at a time. It declines a build while that volume has
 less than 10 GB free, while its own native builds and the offloaded one fill
 its \`concurrency.maxBuilds\`, or while its load per core is at or above its
-\`offload.maxLoadPerCore\`, and reports the reason in its offer. It boots and
+\`server.maxLoadPerCore\`, and reports the reason in its offer. It boots and
 installs nothing. While an offloaded build runs there, it holds one of that
 Mac's \`concurrency.maxBuilds\` slots, so a local Stim build there waits for it
 and counts it as busy; the slot is freed when the build ends, is cancelled or
 its process is gone. Android builds there run on the JDK in stim-server's
 JAVA_HOME (else the macOS default JDK) with the SDK in its ANDROID_HOME (else
 ~/Library/Android/sdk). The client's Gradle daemon stays warm there for
-\`offload.gradleDaemonIdleMinutes\` (default 30; 0 stops it when each build
+\`server.gradleDaemonIdleMinutes\` (default 30; 0 stops it when each build
 ends; a new value applies from the next daemon) and never holds a build
 slot. While none of the client's builds runs, stim-server stops it sooner
 when a build is cancelled, the client is revoked, or the machine has less
 than 2 GB of memory available, and deleting the client's directory under the
 worker root stops it too.
-\`stim-server service install [--serve]\` on the build machine keeps stim-server
+\`stim-server service install [--serve]\` on the remote Mac keeps stim-server
 running as a login LaunchAgent; \`--path-prepend <dir>\` and \`--env KEY=VALUE\`
 pin a PATH entry or variable such as a private CocoaPods that stim-server's
 login-shell environment would otherwise replace.
@@ -9120,7 +9137,7 @@ var macos_default = {
 
 If Stim is not installed globally, replace stim with npx stim.
 
-ios --remote <machine> shares hosting.machines and its separate device-host
+ios --remote <machine> shares remote.machines and its separate device-host
 approval. Read guide lifecycle hosted-ios for simulator placement and Metro.
 
 Run from the directory containing Package.swift. This prototype builds one
@@ -9172,6 +9189,13 @@ Stim Desktop honors. An app that activates itself at launch still takes focus.
 Hosted launches (macos --remote) do not set it.
 macOS artifacts are not cached. This prototype has no --plan, --slot, or reload command.
 A failed build records its error and compiler output without launching an app.
+While it runs, stim status --json reports it as environments[].build with
+platform "macos": phase prepare, compile, install, then launch, and during
+compile detail.unit "steps" with SwiftPM's [done / total] counts (fetching and
+planning are detail.step "configure"). It has no cache lookup, so outcome and
+plannedPhases are null; finished runs and their phase times are in
+environments[].builds.macos. An offloaded build reports the worker's steps the
+same way.
 Runtime stdout and stderr become client records; build output becomes build
 records, all with platform "macos". Unexpected app exits are error records.
 Stim runs the app with NSUnbufferedIO=YES, so Swift print output arrives per
@@ -9179,16 +9203,16 @@ line instead of when the app exits.
 
 BUILD OFFLOAD
 
---build-machine <auto|local|name> overrides STIM_OFFLOAD_MACHINE and the
-machine setting offload.machine (default auto). local builds here; a name
-requires the matching configured and paired build machine, ignoring offload.mode
+--remote-build <auto|local|name> overrides STIM_REMOTE_BUILD and the
+machine setting remote.build (default auto). local builds here; a name
+requires the matching configured and paired remote Mac, ignoring remote.buildMode
 and this Mac's capacity. Any failure is STIM_OFFLOAD_REFUSED without a local xcodebuild, Gradle or
 SwiftPM compile or another machine. Invalid, unlisted or unpaired selections
 refuse before stopping the app or changing its build record. See stim guide errors STIM_OFFLOAD_REFUSED.
 
-With offload.machine auto, offload.mode places these SwiftPM Debug builds:
+With remote.build auto, remote.buildMode places these SwiftPM Debug builds:
 auto builds here while this Mac has capacity, force uses an approved build
-machine when one accepts, and off always builds here. Configure offload.machines
+machine when one accepts, and off always builds here. Configure remote.machines
 and approve build access as described in stim guide settings. The worker needs
 matching Stim, CPU architecture, Xcode and macOS SDK, plus network access to
 fetch package dependencies the first time. It keeps SwiftPM dependencies in a
@@ -9362,15 +9386,15 @@ used.
 ON ANOTHER MAC
 
 stim macos --remote <machine> builds the Debug app on this Mac and runs it on an
-approved hosting Mac over the tailnet, without SSH. The machine must be listed
-in hosting.machines and approved: stim doctor --fix asks it, a person on that
+approved remote Mac over the tailnet, without SSH. The machine must be listed
+in remote.machines and approved: stim doctor --fix asks it, a person on that
 Mac runs stim-server devices grant <id> --device-host or stim-server setup
 with that client node, ticket and expiry (guide settings), and stim doctor then
 records the approval. Stim connects only to the machine's pinned tailnet node.
 A refusal or an unreachable host fails the command; it never launches here
 instead.
 
-The --remote value is a hosting Mac name from hosting.machines. macOS refuses
+The --remote value is a remote Mac name from remote.machines. macOS refuses
 eas and proxy because it has neither backend. It also refuses auto until
 automatic placement ships. These reserved names are case-insensitive and
 trimmed; they refuse with STIM_BAD_ARG before state access or a connection.
@@ -9765,7 +9789,7 @@ const TUTORIAL_STEPS = [
 		optional: true,
 		prompt: TUTORIAL_PROMPTS.machine,
 		section: "machine",
-		manual: ["cd \"{tour}\"", "stim ios --build-machine \"{machine}\" --no-build-cache"]
+		manual: ["cd \"{tour}\"", "stim ios --remote-build \"{machine}\" --no-build-cache"]
 	},
 	{
 		id: "finish",
@@ -9963,7 +9987,7 @@ the app. The intentional button errors may still be in the error log; check
 whether the edit introduced a new error.
 
 PAUSE: end the turn. Point at the purple title in the device view or simulator
-and the title color log line. Phone viewing and an approved build machine are
+and the title color log line. Phone viewing and an approved remote Mac are
 optional user steps; skip them if unwanted. Never pair, approve, or grant
 anything. If the user names an approved machine, the next prompt is
 "${TUTORIAL_PROMPTS.machine}". Otherwise give
@@ -9971,11 +9995,11 @@ anything. If the user names an approved machine, the next prompt is
 			},
 			machine: {
 				summary: "Optionally build using a machine the user names and has approved",
-				body: () => `BUILD MACHINE (OPTIONAL)
+				body: () => `REMOTE MAC (OPTIONAL)
 
 ${paths}
 
-Proceed only when the user names an approved build machine. Substitute that
+Proceed only when the user names an approved remote Mac. Substitute that
 name for {machine}. Never approve, pair, or grant anything. If none is named,
 ask for the name or let the user skip this step.
 
@@ -9983,7 +10007,7 @@ ${commands("machine")}
 
 This step bypasses the artifact cache so the build can use the named machine.
 A named machine refuses without a local fallback. If it refuses, report the
-refusal and offer --build-machine auto or local; do not retry silently.
+refusal and offer --remote-build auto or local; do not retry silently.
 
 PAUSE: end the turn. Point at the build's machine in Desktop or its report in
 stim status --json. Give the next prompt: "${TUTORIAL_PROMPTS.finish}".`