@stim-cli/core 1.13.0 → 1.15.0

package/dist/index-DgLuTAvh.d.mts

@@ -0,0 +1,1826 @@
+import { o as ClaimHandle } from "./ownership-claim-Xxxr9MPp.mjs";
+//#region state/build-capacity.d.ts
+declare function buildSlotsDir(): string;
+declare function buildSlotPath(index: number): string;
+/**
+ * Takes the first free one of `max` `concurrency.maxBuilds` slots, recording `details` and the slot `index`. Returns
+ * null while every slot is held; throws the claim refusal when no slot is busy but one cannot be resolved.
+ */
+declare function tryAcquireBuildSlotClaim({ max, details }: {
+  max: number;
+  details: Record<string, unknown>;
+}): {
+  claim: ClaimHandle;
+  index: number;
+  path: string;
+} | null;
+/**
+ * How busy this Mac is for native builds. `loadPerCore` is the 5-minute load average divided by the CPU count,
+ * rounded to one decimal. `builds` counts this Stim home's runs that hold a live native-run claim and are in
+ * prebuild, pods or compile here, not on a build machine, plus the build slots this Mac holds for other Macs'
+ * offloaded builds. `maxBuilds` is `concurrency.maxBuilds`, 0 when unlimited.
+ */
+interface MachineCapacity {
+  cpus: number;
+  loadPerCore: number;
+  builds: number;
+  maxBuilds: number;
+  maxLoadPerCore: number;
+}
+declare function machineCapacity(): MachineCapacity;
+/** Why a Mac with this capacity should not take another native build; null when it can. */
+declare function saturation(capacity: MachineCapacity): string | null;
+//#endregion
+//#region state/build-machines.d.ts
+/**
+ * A build machine this Mac asked to build on. `machine` is the `offload.machines` entry; `nodeId` is the
+ * worker's tailnet StableID pinned when the request was sent, which every later connection must match.
+ */
+interface BuildMachineCredential {
+  machine: string;
+  nodeId: string;
+  dnsName: string;
+  deviceId: string;
+  deviceToken: string;
+  state: "pending" | "approved";
+  requestedAt: string;
+}
+declare function readBuildMachines(): BuildMachineCredential[];
+//#endregion
+//#region state/config-types.d.ts
+type SettingsObject = Record<string, unknown>;
+interface SupervisorRecord {
+  processToken?: string;
+  pid?: number;
+  port?: number;
+  startedAt?: string;
+  serverPid?: number;
+  mode?: string;
+  [key: string]: unknown;
+}
+interface IosDeviceRecord {
+  deviceUdid?: string;
+  deviceName?: string | null;
+  owned?: boolean;
+  serial?: string;
+  simslimManaged?: boolean;
+  schemeApprovals?: string[];
+  [key: string]: unknown;
+}
+interface AndroidDeviceRecord {
+  avdName?: string;
+  consolePort?: number;
+  serial?: string;
+  kind?: string;
+  deviceName?: string | null;
+  owned?: boolean;
+  setupIncomplete?: boolean;
+  bootPending?: boolean;
+  [key: string]: unknown;
+}
+type DeviceRecord = IosDeviceRecord | AndroidDeviceRecord;
+interface PlatformRecords {
+  ios?: IosDeviceRecord;
+  android?: AndroidDeviceRecord;
+  [platform: string]: DeviceRecord | undefined;
+}
+interface ProjectRecord {
+  ports?: Record<string, number>;
+  metroPort?: number | null;
+  platforms?: PlatformRecords;
+  deviceSlots?: Record<string, PlatformRecords>;
+  supervisor?: SupervisorRecord;
+  settings?: SettingsObject;
+  worktreeRoot?: boolean;
+  worktreeBranch?: string;
+  worktreeBranchOwned?: boolean;
+  worktreeMainRoot?: string;
+  worktreeRemovalComplete?: boolean;
+  worktreePendingBranchSha?: string;
+  label?: string;
+  bundleId?: string;
+  androidPackage?: string;
+  isExpo?: boolean;
+  lastBuild?: Record<string, unknown>;
+  doctorRuns?: Partial<Record<"ios" | "android", DoctorRunRecord>>;
+  [key: string]: unknown;
+}
+interface DoctorRunRecord {
+  at: string;
+  version: string;
+}
+interface RepoRecord {
+  settings?: SettingsObject;
+  [key: string]: unknown;
+}
+interface ConcurrencyLimits {
+  maxBuilds: number;
+  maxDevices: number;
+}
+interface StimConfig {
+  version?: number;
+  projects: Record<string, ProjectRecord>;
+  repos: Record<string, RepoRecord>;
+  tempDir?: unknown;
+  iosSimulatorApp?: unknown;
+  androidEmulatorApp?: unknown;
+  optimizations?: unknown;
+  concurrency?: {
+    maxBuilds?: unknown;
+    maxDevices?: unknown;
+  };
+  pool?: {
+    iosParkedMax?: unknown;
+    androidParkedMax?: unknown;
+  };
+  parked?: {
+    ios?: unknown;
+    android?: unknown;
+  };
+  caches?: {
+    buildCache?: unknown;
+    metroCache?: unknown;
+  };
+  hosting?: {
+    machines?: unknown;
+    agentDriver?: unknown;
+  };
+  server?: {
+    acceptClientBuilds?: unknown;
+  };
+  offload?: {
+    machine?: unknown;
+    machines?: unknown;
+    mode?: unknown;
+    workerRoot?: unknown;
+    maxLoadPerCore?: unknown;
+    gradleDaemonIdleMinutes?: unknown;
+  };
+  [key: string]: unknown;
+}
+type Config = StimConfig;
+//#endregion
+//#region state/config.d.ts
+declare function withConfigLock<T>(fn: () => T): T;
+declare function configCorruptRepair(path?: string): string;
+/** The build worker root: `offload.workerRoot` when it is absolute, else `$STIM_HOME/build-worker`. */
+declare function buildWorkerRoot(config?: Config | null): string;
+declare function loadConfig(): Config | null;
+declare function getProject(projectPath: string): ProjectRecord | null;
+declare function getConcurrencyLimits({ env }?: {
+  env?: NodeJS.ProcessEnv;
+}): ConcurrencyLimits;
+declare function getProjectSettings(projectPath: string): Record<string, unknown>;
+declare function getProjectSetting(projectPath: string, dottedKey: string): unknown;
+declare function getRepoSettings(gitCommonDir: string): Record<string, unknown>;
+declare function isPathPrefix(prefix: string, path: string): boolean;
+declare function findEnclosingWorktreeRoot(projectPath: string): string | null;
+declare function allMetroPorts(): number[];
+declare function findProjectByMetroPort(port: number): string | null;
+//#endregion
+//#region state/json-file.d.ts
+/**
+ * Runs `fn` with each state file read from disk at most once: inside it, including after an `await`, `readStateFile`
+ * returns the text of the first read of that path, and a path found missing stays missing. Callers still parse every time, so no two
+ * share a mutable object. Only for computations that write none of the files they read.
+ */
+declare function withStateReadCache<T>(fn: () => T): T;
+declare function readStateFile(path: string): string;
+declare function readJsonFile(path: string): unknown;
+declare function isJsonObject(value: unknown): value is Record<string, unknown>;
+declare function readJsonObject(path: string): Record<string, unknown> | null;
+//#endregion
+//#region state/ledgers.d.ts
+type CreatedDevicePlatform = "ios" | "android" | "web";
+/** `web` lists the absolute paths of browser profile directories Stim created. */
+interface CreatedDevices {
+  ios: ReadonlySet<string>;
+  android: ReadonlySet<string>;
+  web: ReadonlySet<string>;
+}
+declare function readCreatedDevices(): CreatedDevices;
+interface EasSessionClaim {
+  sessionId: string;
+  name: string;
+  platform: "ios" | "android";
+  workspaceRoot: string;
+  workspaceHome: string;
+  stateFile: string;
+}
+interface EasSessionLedgerRead {
+  claims: Map<string, EasSessionClaim>;
+  notice: string | null;
+  safe: boolean;
+}
+/** Returns the claim normalized to canonical paths, or null when it is not a valid claim for `id`. */
+declare function validEasSessionClaim(id: string, value: unknown): EasSessionClaim | null;
+declare function readEasSessionLedger(root?: string): EasSessionLedgerRead;
+//#endregion
+//#region state/ndjson.d.ts
+interface NdjsonRecord {
+  ts?: number;
+  src?: string;
+  level?: string;
+  msg?: string;
+  /** With `logs --errors --json`: the code frame and stack lines Expo printed after this error. */
+  context?: string[];
+  [key: string]: unknown;
+}
+declare const LEVELS: string[];
+declare const SOURCES: string[];
+declare function levelRank(level?: string): number;
+declare function parseNdjsonLine(line: unknown): NdjsonRecord | null;
+declare function parseNdjsonText(text: unknown): NdjsonRecord[];
+declare function readNdjsonGenerations(file: string): NdjsonRecord[];
+//#endregion
+//#region state/error-entries.d.ts
+/**
+ * The number of rows a log list shows for `records`, an error query's result in log order. Stim Desktop's
+ * `LogEntryList` and the phone's `groupRecords` group the same way and replay the same vectors: in Expo's dev
+ * server one failed bundle is a `Bundling failed` marker line, the error line and a failed bundle response,
+ * which the apps list as one row, and every other record is its own row.
+ */
+declare function countErrorEntries(records: readonly NdjsonRecord[]): number;
+//#endregion
+//#region state/logs-query.d.ts
+interface SinceResult {
+  ms?: number;
+  error?: string;
+}
+interface GrepResult {
+  re?: RegExp;
+  error?: string;
+}
+interface MarkerWindow {
+  launchTs: number | null;
+  bundleTs: number | null;
+  pageLoadTs: number | null;
+}
+interface QueryCriteria {
+  slot?: string;
+  includeAppDeviceErrors?: boolean;
+  sources?: string[];
+  minLevel?: string;
+  grep?: RegExp;
+  sinceTs?: number;
+  errorsOnly?: boolean;
+  markerTs?: number;
+  bundleMarkerTs?: number;
+}
+interface TailState {
+  offset: number;
+  partial: string;
+}
+declare function parseSince(text: unknown): SinceResult;
+declare function compileGrep(pattern: unknown): GrepResult;
+declare const ERROR_SOURCES: string[];
+declare function markerWindow(records: NdjsonRecord[]): MarkerWindow;
+/**
+ * The platform a bundle marker speaks for, lowercased: its `platform` field, or the tag @expo/cli prints before
+ * "Bundled" ("iOS", "Android", "Web", "RSC(iOS)" as ios, or an environment tag such as "DOM"). Null when unknown.
+ */
+declare function bundleMarkerPlatform(record: NdjsonRecord): string | null;
+declare function recordMatches(record: NdjsonRecord | null | undefined, criteria?: QueryCriteria): boolean;
+declare function buildCriteria({ slot, sources, minLevel, since, grep, errorsOnly, markerTs, bundleMarkerTs, now }?: {
+  slot?: string;
+  sources?: string[];
+  minLevel?: string;
+  since?: string | null;
+  grep?: string | RegExp | null;
+  errorsOnly?: boolean;
+  markerTs?: number;
+  bundleMarkerTs?: number;
+  now?: number;
+}): QueryCriteria;
+declare function logFiles(dir: string): string[];
+declare function fileSizes(dir: string): Record<string, number>;
+declare function readLogRecords(dir: string, include?: (name: string) => boolean): NdjsonRecord[];
+type ExpoContextTarget = "msg" | "field";
+/**
+ * Adds the code frame and stack lines Expo printed after each Expo error record, either joined into
+ * `msg` or as a `context` string array.
+ */
+declare function attachExpoErrorContext(all: NdjsonRecord[], matched: NdjsonRecord[], into?: ExpoContextTarget): NdjsonRecord[];
+declare function queryLogs({ slot, dir, records, sources, minLevel, since, grep, tail, errorsOnly, errorContext, now }?: {
+  slot?: string;
+  dir?: string;
+  records?: NdjsonRecord[];
+  sources?: string[];
+  minLevel?: string;
+  since?: string;
+  grep?: string | RegExp;
+  tail?: number;
+  errorsOnly?: boolean;
+  errorContext?: boolean;
+  now?: number;
+}): NdjsonRecord[];
+declare function tailRead(prev: TailState | null | undefined, size: number): {
+  start: number;
+  prev: TailState;
+};
+declare function advanceTail(prev: TailState | null | undefined, chunk: string | null | undefined, size: number): {
+  state: TailState;
+  records: NdjsonRecord[];
+};
+declare function followLogs({ dir, onRecord, criteria, intervalMs, offsets, errorContext }: {
+  dir: string;
+  onRecord: (record: NdjsonRecord) => void;
+  criteria?: QueryCriteria;
+  intervalMs?: number;
+  offsets?: Record<string, number> | null;
+  /** Holds each Expo error until a poll adds no more of its code frame or stack lines, then attaches them. */
+  errorContext?: ExpoContextTarget;
+}): () => void;
+declare function sortByTs(records: NdjsonRecord[]): NdjsonRecord[];
+//#endregion
+//#region state/paths.d.ts
+declare function getConfigPath(): string;
+declare function configLockPath(): string;
+declare function workspaceMetadataFile(projectRoot: string): string;
+declare function workspaceLogsDir(projectRoot: string): string;
+/** Device screen footage stim-server records for the workspace, one directory per platform and slot. */
+declare function workspaceRecordingsDir(projectRoot: string): string;
+declare function workspaceLogErrorIndex(projectRoot: string): string;
+declare function workspaceDerivedData(projectRoot: string): string;
+declare function workspaceGradleBuild(projectRoot: string): string;
+declare function workspaceBuildDetailFile(projectRoot: string): string;
+/** The agent sessions that stopped running in the workspace in the last `ENDED_AGENT_RETENTION_MS`. */
+declare function workspaceEndedAgentsFile(projectRoot: string): string;
+declare function workspaceEndedAgentsLock(projectRoot: string): string;
+declare function supervisorPidFile(projectRoot: string): string;
+declare function workspaceStateFile(projectRoot: string): string;
+declare function workspaceStateLock(projectRoot: string): string;
+declare function supervisorLogFile(projectRoot: string): string;
+declare function emulatorLogFile(projectRoot: string): string;
+declare function sharedCompilationCache(): string;
+declare function sharedCcache(): string;
+declare function sharedGradle(): string;
+declare function sharedPods(): string;
+declare function createdDevicesFile(): string;
+declare function gitMergeCacheDir(): string;
+declare function pullRequestCacheDir(): string;
+declare function agentSessionsCacheFile(): string;
+declare function diskUsageCacheDir(): string;
+/** The build machines this Mac paired with, each with its pinned tailnet node and device token. */
+declare function buildMachinesFile(): string;
+declare function buildMachinesLock(): string;
+/** The hosting machines this Mac asked for access, separate from build credentials. */
+declare function deviceHostMachinesFile(): string;
+declare function deviceHostMachinesLock(): string;
+declare function deviceHostMachinesClaims(): string;
+declare function createdDevicesLock(): string;
+/** The EAS session ledger lives under the real home directory, never under STIM_HOME. */
+declare function easMachineStateRoot(): string;
+declare function easSessionLedgerFile(root?: string): string;
+declare function easSessionLedgerLock(root?: string): string;
+/** Where stim-server records, one file per server process, the devices whose frames a client subscribes to. */
+declare function deviceViewersDir(): string;
+declare function statsFile(): string;
+//#endregion
+//#region state/recordings.d.ts
+/** The footage stim-server keeps per device: the last 15 minutes recorded, however long ago. */
+declare const RECORDING_FOOTAGE_MS: number;
+/** The recordings of every workspace of one Stim home together; past it the oldest footage goes first. */
+declare const RECORDING_CAP_BYTES: number;
+/** The platforms stim-server records: owned simulators and emulators, and the Stim-owned Chrome page. */
+declare const RECORDING_PLATFORMS: readonly ["ios", "android", "web"];
+type RecordingPlatform = (typeof RECORDING_PLATFORMS)[number];
+/**
+ * One file of H.264 footage. A closed segment is named `<start>-<end>.seg`, in epoch milliseconds of its first and
+ * last access unit; the segment being written is `<start>.part`, and its end is its modification time.
+ */
+interface RecordedSegment {
+  file: string;
+  start: number;
+  end: number;
+  bytes: number;
+  open: boolean;
+}
+interface RecordedDevice {
+  platform: RecordingPlatform;
+  slot: string;
+  dir: string;
+  segments: RecordedSegment[];
+}
+/** The directory under a workspace's recordings that holds one device slot's footage. */
+declare function recordingDeviceName(platform: RecordingPlatform, slot: string): string;
+/** Segment names hold whole milliseconds: the start rounded down and the end rounded up. */
+declare function closedSegmentName(start: number, end: number): string;
+declare function openSegmentName(start: number): string;
+/** The segments in one device directory, oldest first. Files that are not segments are left out. */
+declare function listSegments(dir: string): RecordedSegment[];
+/** Every device slot recorded under a workspace's recordings directory. */
+declare function listRecordedDevices(recordingsDir: string): RecordedDevice[];
+declare function recordedBytes(devices: readonly RecordedDevice[]): number;
+/**
+ * The oldest closed segments to delete so that one device keeps at most `footageMs` of footage. Time between
+ * segments, while nothing was recorded, does not count. The open segment is never chosen.
+ */
+declare function footageDrops(segments: readonly RecordedSegment[], footageMs: number): RecordedSegment[];
+/** The oldest closed segments across all devices to delete so that together they hold at most `capBytes`. */
+declare function capDrops(devices: readonly RecordedDevice[], capBytes: number): RecordedSegment[];
+/**
+ * Whether stim-server records a workspace's devices: `STIM_RECORDING`, then `recording.enabled` in the workspace,
+ * repo and machine layers, in that order, and true by default.
+ */
+declare function recordingEnabled(env: NodeJS.ProcessEnv, layers: readonly unknown[]): boolean;
+//#endregion
+//#region state/settings-registry.d.ts
+declare const ANDROID_COMPILER_CACHE_CHOICES: readonly ["auto", "ccache", "cas", "none"];
+declare const ANDROID_PCH_CHOICES: readonly ["auto", "on", "off"];
+type TunnelMode = "auto" | "off" | "expo" | "cloudflared" | "ngrok" | "tailscale";
+declare const TUNNEL_MODES: readonly TunnelMode[];
+type RemoteDeviceBackend = "proxy" | "eas";
+type SettingScope = "machine" | "workspace" | "repo" | "committed";
+declare const SETTING_SCOPES: readonly SettingScope[];
+type SettingType = {
+  kind: "string";
+  pattern?: string;
+  patternHelp?: string;
+} | {
+  kind: "path";
+  absolute?: boolean;
+  relative?: boolean;
+} | {
+  kind: "strings";
+} | {
+  kind: "number";
+  integer?: boolean;
+  minimum?: number;
+  maximum?: number;
+} | {
+  kind: "boolean";
+} | {
+  kind: "choice";
+  choices: readonly string[];
+} | {
+  kind: "object";
+} | {
+  kind: "bundle-url";
+};
+/**
+ * One setting Stim reads. `scopes` are the layers the setting may be written to;
+ * `committedAt: 'repository'` reads the committed layer from the repository root's
+ * `.stim.json` instead of the app's. A `sensitive` value is never printed and is
+ * written to `.stim.json` only as an `env:` or `file:` reference. `scopedHomeValue`
+ * replaces every layer and the default while STIM_HOME is set and `env` is not.
+ * `desktopDefault` replaces `default` on macOS while Stim Desktop is installed.
+ */
+interface SettingDefinition {
+  key: string;
+  type: SettingType;
+  scopes: readonly SettingScope[];
+  description: string;
+  default?: string | number | boolean;
+  env?: string;
+  sensitive?: boolean;
+  committedAt?: "repository";
+  scopedHomeValue?: number;
+  desktopDefault?: string;
+}
+interface SettingEntry {
+  key: string;
+  value: unknown;
+  origin: SettingScope | "env" | "default" | null;
+  layers: Partial<Record<SettingScope, unknown>>;
+  env?: {
+    name: string;
+    value: string;
+  };
+  sensitive?: true;
+  defaultReason?: string;
+}
+/** The payload `stim settings --json` prints. */
+interface SettingsPayload {
+  project: string | null;
+  files: Partial<Record<SettingScope, string>>;
+  settings: SettingEntry[];
+  unknown: Array<{
+    key: string;
+    scope: SettingScope;
+    file: string;
+    value: unknown;
+  }>;
+}
+declare const REMOTE_DEVICE_BACKENDS: readonly RemoteDeviceBackend[];
+declare const IOS_SIMULATOR_APPS: readonly ["xcode", "siniulator", "stim-desktop"];
+declare const ANDROID_EMULATOR_APPS: readonly ["emulator", "stim-desktop"];
+declare const OFFLOAD_MODES: readonly ["auto", "force", "off"];
+type OffloadMode = (typeof OFFLOAD_MODES)[number];
+declare const WEB_VIEWPORTS: readonly ["desktop", "phone"];
+type WebViewport = (typeof WEB_VIEWPORTS)[number];
+declare const SETTINGS: readonly SettingDefinition[];
+declare function settingDefinition(key: string): SettingDefinition | null;
+declare function isLayeredSetting(setting: SettingDefinition): boolean;
+declare const SETTING_GROUPS: readonly string[];
+declare function expectedShape(type: SettingType): string;
+declare function acceptsShape(setting: SettingDefinition, value: unknown): boolean;
+declare function settingValueError(setting: SettingDefinition, value: unknown): string | null;
+declare function isSensitiveReference(value: unknown): boolean;
+/**
+ * Coerces raw text (a CLI argument or an environment variable) through a setting's
+ * registry type, the same way for both sources. Types whose values are not written
+ * as bare text (boolean, number, strings, object) are read as JSON; a value that
+ * fails to parse is left as the original string so `settingValueError` reports it. A boolean also reads `1` and `0`.
+ */
+declare function coerceSettingText(setting: SettingDefinition, raw: string): unknown;
+//#endregion
+//#region state/settings-schema.d.ts
+declare const SETTINGS_SCHEMA_FILE = "settings.schema.json";
+declare const SETTINGS_SCHEMA_URL: string;
+type JsonSchema = Record<string, unknown>;
+/**
+ * The published settings schema. The root describes a committed `.stim.json`;
+ * `$defs.machine` describes the settings keys of `$STIM_HOME/config.json`.
+ * Every leaf carries `x-stim` with its dotted key, kind, writable scopes,
+ * environment override, and sensitivity.
+ */
+declare function settingsJsonSchema(): JsonSchema;
+//#endregion
+//#region state/hosted-app.d.ts
+interface HostedAppFile {
+  path: string;
+  kind: "file" | "exec" | "link";
+  size: number;
+  sha256: string;
+}
+interface HostedAppOffer {
+  session: string;
+  attempt: string;
+  bundleId: string;
+  mode: "development" | "release";
+  devClientScheme?: string;
+  arguments?: string[];
+  manifest: {
+    sha256: string;
+    size: number;
+  };
+}
+interface HostedAppDelivery extends Omit<HostedAppOffer, "manifest"> {
+  state: "receiving" | "installing" | "installed" | "unknown";
+  launched: true | "unverified" | null;
+  notice?: string;
+}
+interface HostedAppRecord extends HostedAppDelivery {
+  manifest: HostedAppOffer["manifest"];
+  files: HostedAppFile[];
+}
+declare const HOSTED_APP_CHUNK_BYTES: number;
+declare function hostedAppAttempt(value: unknown): value is string;
+declare function hostedAppArea(session: string, attempt: string, workerHome?: string): string;
+/** At most 32 plain arguments of 1024 characters (8192 in total), with no NUL, CR or LF. */
+declare function validHostedAppArguments(value: unknown): value is string[];
+declare function parseHostedAppOffer(value: unknown): HostedAppOffer | null;
+/** Relative normalized paths, with no file or link as another entry's ancestor. */
+declare function parseHostedAppManifest(value: unknown): HostedAppFile[] | null;
+/** Reads a server-written receipt; malformed or missing established state remains unresolved. */
+declare function readHostedAppMetadata(session: string, attempt: string, workerHome?: string): Omit<HostedAppRecord, "files">;
+declare function readHostedApp(session: string, attempt: string, workerHome?: string): HostedAppRecord;
+//#endregion
+//#region state/hosted-macos.d.ts
+/** App slots one host offers; a slot names the host-assigned bundle id `<bundleId>.hosted<slot>`. */
+declare const HOSTED_MACOS_APP_SLOTS = 64;
+declare const HOSTED_AGENT_DRIVERS: readonly ["none", "agent-device"];
+type HostedAgentDriverName = (typeof HOSTED_AGENT_DRIVERS)[number];
+/** What a host reports in a macOS offer: no simulator is created, so the choice is the host itself. */
+interface HostedMacosChoice {
+  architecture: "arm64" | "x86_64";
+  macosVersion: string;
+}
+/** A ready hosted macOS session's identity: the host it runs on and the app slot reserved for it. */
+interface HostedMacosDevice extends HostedMacosChoice {
+  appSlot: number;
+}
+/**
+ * The rest of an agent-device `macos-app` lease's owner scope, which a client names on every request:
+ * `deviceKey` is `<bundleId>@<pid>` of the hosted app.
+ */
+interface HostedAgentLease {
+  tenant: string;
+  runId: string;
+  clientId: string;
+  deviceKey: string;
+}
+/**
+ * Agent control the host grants a client for one installed hosted app, sent only over that client's approved
+ * device-host connection and never journaled. `none` means the host's `hosting.agentDriver` starts no driver.
+ * `path` is the session's base route on the host, `scope` the driver's handle that limits it to this one app,
+ * and `lease` the scope the driver's lease was allocated with.
+ */
+type HostedAgentGrant = {
+  driver: "none";
+} | {
+  driver: Exclude<HostedAgentDriverName, "none">;
+  path: string;
+  token: string;
+  scope: string;
+  lease: HostedAgentLease;
+};
+/** `app.launch` and `app.attach` results; a host includes `agent` once the app is installed. */
+type HostedAppLaunch = HostedAppDelivery & {
+  agent?: HostedAgentGrant;
+};
+/**
+ * Agent control as the client hands it to a coding agent: secrets stay in files Stim writes with mode
+ * 0600, and `command` shows how to address the hosted app. Never carries a token inline. `setting` names
+ * the hosting Mac's setting that turns a driver on.
+ */
+type HostedAgentAccess = {
+  driver: "none";
+  setting: "hosting.agentDriver";
+} | {
+  driver: "agent-device";
+  remoteConfig: string;
+  command: string;
+};
+/** Where a workspace's macOS app runs when `stim macos --remote` placed it on another Mac. */
+interface HostedMacosPlacement {
+  machine: string;
+  session: string;
+  appSlot: number;
+  appAttempt: string;
+  /** The host-assigned id the running app uses, `hostedMacosBundleId(<offered id>, appSlot)`. */
+  bundleId: string;
+  agent: HostedAgentAccess;
+}
+declare function hostedMacosAppSlot(value: unknown): value is number;
+declare function hostedMacosBundleId(bundleId: string, appSlot: number): string;
+declare function parseHostedMacosChoice(value: unknown): HostedMacosChoice | null;
+declare function parseHostedMacosDevice(value: unknown): HostedMacosDevice | null;
+/** A grant naming a driver this client does not know is not usable; it parses as null. */
+declare function parseHostedAgentGrant(value: unknown): HostedAgentGrant | null;
+declare function parseHostedMacosPlacement(value: unknown): HostedMacosPlacement | null;
+//#endregion
+//#region state/macos.d.ts
+interface MacosProcess {
+  pid: number;
+  processToken: string;
+  startedAtMicros: number;
+}
+interface MacosBuild {
+  state: "running" | "ok" | "failed";
+  startedAt: string;
+  finishedAt?: string;
+  durationMs?: number;
+  error?: string;
+  errorCode?: string;
+  buildMachine?: string;
+  builtOn?: string;
+  offloadedTo?: string;
+  offloadFallback?: string;
+}
+interface MacosAppRecord {
+  launchId: string;
+  arguments: string[];
+  product: string;
+  bundle: string;
+  bundleId: string;
+  executable: string;
+  build: MacosBuild;
+  supervisor?: MacosProcess;
+  app?: MacosProcess;
+  /** Set when `stim macos --remote` reserved a session on another Mac; the app then has no local process. */
+  host?: HostedMacosPlacement;
+  /** Host launch evidence: true for a live app; status can override it in memory after probing the session. */
+  hostLaunched?: boolean | "unverified";
+}
+interface MacosAppState extends MacosAppRecord {
+  state: "running" | "orphaned" | "stopped" | "unverified";
+}
+declare function parseMacosRecord(value: unknown): MacosAppRecord | null;
+declare function readMacosRecord(root: string): MacosAppRecord | null;
+declare function readHostedMacosApp(home: string): MacosAppRecord | null;
+declare function macosAppState(record: MacosAppRecord | null): MacosAppState | null;
+//#endregion
+//#region state/workspace-state.d.ts
+interface WorkspaceState {
+  supervisor?: Record<string, unknown>;
+  collectors?: Record<string, unknown>;
+  lastBuild?: Record<string, unknown>;
+  launches?: Record<string, unknown>;
+  remoteDevice?: Record<string, unknown>;
+  metroTunnel?: Record<string, unknown>;
+  [key: string]: unknown;
+}
+declare const IDLE_STOP_KEY = "devServerStop";
+/** Why the supervisor last stopped the dev server on its own: `metro.idleStopMinutes` with no use. */
+interface IdleStopRecord {
+  reason: "idle";
+  at: string;
+  idleMinutes: number;
+}
+declare function readIdleStop(state: WorkspaceState | null | undefined): IdleStopRecord | null;
+declare const DEVICE_IDLE_SHUTDOWN_KEY = "deviceIdleShutdowns";
+/** An owned simulator or emulator the supervisor shut down after `devices.idleShutdownMinutes` with no use. */
+interface DeviceIdleShutdownRecord {
+  at: string;
+  idleMinutes: number;
+}
+/** The recorded idle shutdowns by device slot key (`ios`, `android`, `ios:<slot>`). */
+declare function readDeviceIdleShutdowns(state: WorkspaceState | null | undefined): Record<string, DeviceIdleShutdownRecord>;
+declare const DEV_SERVER_STOP_REQUEST_KEY = "devServerStopRequest";
+/** A Stim component's intent to stop the supervisor with `processToken`, written before it signals. */
+interface DevServerStopRequest {
+  processToken: string;
+  by: string;
+  pid: number;
+  at: string;
+  workspace?: string;
+}
+declare function readDevServerStopRequest(state: WorkspaceState | null | undefined): DevServerStopRequest | null;
+/**
+ * Why the dev server last stopped, stored under `IDLE_STOP_KEY`. `requested` names the Stim component that
+ * asked; `signal` is a SIGTERM or SIGINT no Stim component asked for; `server-exited` is the dev server
+ * process exiting on its own.
+ */
+type DevServerStopRecord = IdleStopRecord | {
+  reason: "requested";
+  at: string;
+  by: string;
+  byPid: number;
+  byWorkspace?: string;
+} | {
+  reason: "signal";
+  at: string;
+  signal: string;
+} | {
+  reason: "server-exited";
+  at: string;
+  mode: string;
+  code: number | null;
+  signal: string | null;
+};
+/** A stopped dev server's last cause in status; `vanished` is a supervisor proven gone that recorded none. */
+type MetroLastStop = DevServerStopRecord | {
+  reason: "vanished";
+  pid: number;
+  startedAt: string | null;
+};
+declare function readDevServerStop(state: WorkspaceState | null | undefined): DevServerStopRecord | null;
+/** Each platform's latest run; `lastBuild` holds whichever platform ran last. */
+declare const LAST_BUILD_KEYS: Readonly<Record<StatsPlatform, string>>;
+declare const BUILD_HISTORY_KEY = "buildHistory";
+declare const BUILD_HISTORY_LIMIT = 10;
+/** A recorded miss reason in the shape status reports, without `baseline.cacheKey`; null when malformed. */
+declare function parseMissReason(value: unknown): BuildMissReason | null;
+/**
+ * The first diagnostics of a failed build in the shape a last-build record stores and `status` reports, the
+ * ones with a source position first.
+ */
+declare function buildDiagnostics(value: unknown): BuildDiagnostic[];
+declare function readLastBuilds(state: WorkspaceState | null | undefined): Partial<Record<StatsPlatform, LastBuildReport>>;
+/** Each platform's recorded runs, newest first, at most `BUILD_HISTORY_LIMIT` each. */
+declare function readBuildHistory(state: WorkspaceState | null | undefined): Partial<Record<StatsPlatform, BuildHistoryEntry[]>>;
+declare function readWorkspaceState(root: string): WorkspaceState | null;
+declare function lastUseFrom(state: WorkspaceState | null, logMtimes: readonly number[]): number;
+declare function workspaceLastUsed(root: string): number;
+declare const WARM_KEY = "warm";
+/** How long a successful warm keeps a workspace `ready` when nothing runs in it. */
+declare const READY_PHASE_MS: number;
+/**
+ * What `stim worktree warm` last recorded in a workspace: a warm in progress, held by the ownership claim
+ * `claim` names, or a successful warm that finished at `at`.
+ */
+type WarmRecord = {
+  phase: "warming";
+  step: WarmStep;
+  startedAt: string;
+  claim: {
+    root: string;
+    claimId: string;
+  };
+} | {
+  phase: "ready";
+  at: string;
+};
+declare function readWarmRecord(state: WorkspaceState | null | undefined): WarmRecord | null;
+declare const WORKSPACE_AGENT_KEY = "agentSession";
+/**
+ * The coding-agent session whose shell ran the Stim command that last recorded `lastUsedAt`, with that command's
+ * working directory as `cwd` and its time as `lastActiveAt`.
+ */
+declare function readWorkspaceAgent(state: WorkspaceState | null | undefined): AgentSession | null;
+//#endregion
+//#region state/status.d.ts
+type StatsPlatform = "ios" | "android";
+type RunOutcomeKind = "hit" | "cold";
+declare const BUILD_PHASES: readonly ["prepare", "cache-lookup", "wait", "prebuild", "pods", "compile", "device", "install", "launch"];
+type BuildPhase = (typeof BUILD_PHASES)[number];
+type ActiveBuildState = "running" | "stale" | "unknown";
+/**
+ * Where a running build compiles: `local`, or the build machine it was offloaded to, with the phase it is in there
+ * (`sync`, `deps`, `prebuild`, `pods`, `build` or `fetch`) and when the offload and that phase started.
+ */
+type BuildPlacement = "local" | {
+  host: string;
+  phase: string;
+  startedAt: string;
+  phaseStartedAt: string;
+};
+interface BuildReport {
+  platform: StatsPlatform;
+  slot: string;
+  state: ActiveBuildState;
+  phase: BuildPhase;
+  startedAt: string;
+  phaseStartedAt: string;
+  outcome: RunOutcomeKind | null;
+  /** Whether `outcome` is this run's own; before its cache lookup resolves it is the project's latest outcome. */
+  outcomeKnown: boolean;
+  /** The resolved lookup result; absent before resolution and when the run skips cache lookup. */
+  cacheLookupOutcome?: "hit" | "miss";
+  expectedMs: number | null;
+  expectedPhaseMs: number | null;
+  basis: number;
+  /**
+   * The phases a run like this one goes through, in order, with each one's median in milliseconds, from the same
+   * runs as `expectedMs`; null without comparable runs. The current phase can be one the plan does not list.
+   */
+  plannedPhases: PlannedPhase[] | null;
+  /** Why the run's cache lookup missed, once the run knows; `baseline` omits `cacheKey`. */
+  missReason?: BuildMissReason;
+  /**
+   * True while `missReason` is the miss of the key the run looked up first and the run will prebuild or install pods,
+   * then look the key up again. A hit on the second lookup removes `missReason` and sets `outcome` to `hit`.
+   */
+  missProvisional?: true;
+  /** What the native build tool is doing now, once it printed a line Stim recognizes. */
+  detail?: BuildDetail;
+  placement: BuildPlacement;
+  /** While `phase` is `wait`: the workspace whose build of the same artifact this run waits on, when it is known. */
+  waitingOn?: {
+    path: string;
+  };
+}
+/** One phase a running build is expected to go through, and its median duration in comparable runs. */
+interface PlannedPhase {
+  phase: BuildPhase;
+  expectedMs: number;
+}
+/** The native build tool's step inside a build's `compile` phase. */
+declare const NATIVE_BUILD_STEPS: readonly ["configure", "compile", "link", "resources", "script", "dex", "package", "sign"];
+type NativeBuildStep = (typeof NATIVE_BUILD_STEPS)[number];
+/**
+ * A running build's progress as its tool reports it. `unit` is `targets` for xcodebuild and `tasks` for Gradle.
+ * xcodebuild's `done` counts targets it finished and `total` the targets in its dependency graph, which includes
+ * targets with nothing to do; Gradle's `done` counts the tasks it reported, with a null `total`. They are counts, not
+ * a completion fraction. `status` reports the detail only during the `compile` phase. `line` is
+ * the latest compile, link or task line with paths shortened to file names.
+ */
+interface BuildDetail {
+  step: NativeBuildStep | null;
+  unit: "targets" | "tasks" | null;
+  done: number | null;
+  total: number | null;
+  line: string | null;
+  updatedAt: string;
+}
+/** Where a build's app came from: a cache tier, or `false` when it compiled or failed before one was found. */
+type BuildCacheHit = "local" | "remote" | false;
+/** A platform's most recent `ios` or `android` run in one workspace. */
+interface LastBuildReport {
+  platform: StatsPlatform;
+  status: "ok" | "failed";
+  cacheHit: BuildCacheHit;
+  cacheSkipped: boolean;
+  durationMs: number | null;
+  fingerprint: string | null;
+  startedAt: string;
+  finishedAt: string | null;
+  errorCode?: string;
+  missReason?: BuildMissReason;
+  /** The selected auto, local, or configured machine entry; present on new build records, including cache hits. */
+  buildMachine?: string;
+  /** Where compilation ran: here or a machine name; absent when no build ran. */
+  builtOn?: string;
+  /** The build machine that compiled the app when the build was offloaded. */
+  offloadedTo?: string;
+  /** Why the run built here after it considered offloading; absent when it offloaded or never considered it. */
+  offloadFallback?: string;
+  /** The first compiler diagnostics of a failed build, when the build tool reported any. */
+  diagnostics?: BuildDiagnostic[];
+  /** Present on a failed run: what failed, from `buildCause`. */
+  cause?: BuildCause;
+}
+/**
+ * A failed run's cause: the first diagnostic with a file and a line, keyed `file:line`, else the run's error code
+ * (or `failed`), with null `file` and `line`. Consecutive failures with the same `key` failed the same way.
+ */
+interface BuildCause {
+  key: string;
+  file: string | null;
+  line: number | null;
+}
+/** How a recorded build ended. `interrupted` is a run whose process ended without recording a result. */
+declare const BUILD_RESULTS: readonly ["succeeded", "failed", "cancelled", "interrupted"];
+type BuildResult = (typeof BUILD_RESULTS)[number];
+/**
+ * One run in a workspace's recent build history. `configuration` is the iOS configuration or the Android
+ * variant the run built, `Debug` or `debug` by default, and null when the run ended before resolving it.
+ * `phases` holds the milliseconds spent in each phase the run entered. An interrupted run has null
+ * `durationMs` and `finishedAt`, no cache facts, and 0 for the phase it stopped in.
+ */
+interface BuildHistoryEntry extends LastBuildReport {
+  result: BuildResult;
+  slot: string;
+  configuration: string | null;
+  cacheKey: string | null;
+  phases: Partial<Record<BuildPhase, number>>;
+}
+/** One compiler error from a failed build: where it is, when the tool said, and its message. */
+interface BuildDiagnostic {
+  file: string | null;
+  line: number | null;
+  column: number | null;
+  message: string;
+}
+/** What kind of native input a changed fingerprint source is. */
+type BuildMissCategory = "native-dependency" | "config-plugin" | "app-config" | "app-asset" | "package" | "native-dir" | "autolinking" | "package-scripts" | "file" | "other";
+interface BuildMissChange {
+  source: string;
+  change: "added" | "removed" | "changed";
+  category: BuildMissCategory;
+}
+/**
+ * Why a run compiled instead of installing a cached app. `changes` holds at most 20 entries,
+ * ordered by importance; `changeCount` is the full number of changed fingerprint sources.
+ * Only a plan reports `prebuild-pending`: the run would prebuild before compiling, so the changes
+ * compare the fingerprint before that prebuild.
+ */
+interface BuildMissReason {
+  kind: "changed" | "no-baseline" | "same-sources" | "cache-skipped" | "fingerprint-error" | "prebuild-pending";
+  summary: string;
+  changes: BuildMissChange[];
+  changeCount: number;
+  /** `cacheKey` is kept in workspace state so a later miss can find this baseline; status omits it. */
+  baseline: {
+    fingerprint: string;
+    cacheKey?: string;
+    from: "workspace" | "project";
+  } | null;
+  rekeyedBy: string[];
+}
+/** The payload `stim ios --plan --json` and `stim android --plan --json` print. */
+interface BuildPlanPayload {
+  platform: StatsPlatform;
+  slot?: string;
+  fingerprint: string;
+  cacheKey: string | null;
+  cacheHit: BuildCacheHit;
+  provider: string | null;
+  cacheSkipped: boolean;
+  prebuild: "none" | "generate" | "regenerate" | "refuse" | null;
+  outcome: RunOutcomeKind | null;
+  expectedMs: number | null;
+  basis: number;
+  /** On a predicted miss with cache reads on, why the cache has no app; `baseline` omits `cacheKey`. */
+  missReason?: BuildMissReason;
+  refusal?: {
+    code: string;
+    message: string;
+    remedy: string;
+  };
+}
+type ActivityState = "driven" | "active" | "idle" | "unknown";
+interface ActivityDriver {
+  tool: string;
+  pid: number | null;
+  since: string | null;
+}
+/** The kinds of evidence that date a device's last activity, in the order `recent` lists them. */
+declare const ACTIVITY_RECENCY_BASES: readonly ["agent-action", "device-log", "metro-bundle", "workspace-use", "supervisor-start", "page-log", "viewer"];
+type ActivityRecencyBasis = (typeof ACTIVITY_RECENCY_BASES)[number];
+interface DeviceActivity {
+  state: ActivityState;
+  driver?: ActivityDriver;
+  lastActivityAt?: string;
+  /** The newest time of each kind of evidence behind `lastActivityAt`, so a reader can leave out app log chatter. */
+  recent?: Partial<Record<ActivityRecencyBasis, string>>;
+  basis: string[];
+}
+/** Every state a device's app process can report. */
+declare const APP_PROCESS_STATES: readonly ["running", "stopped", "unknown"];
+/**
+ * Whether the workspace's app process is alive on a device now. This is current process state, not launch evidence:
+ * `launched` in an `ios` or `android` result stays the record of one launch. `id` is the bundle identifier or
+ * package that was checked; `state` is "unknown" when the process listing could not be read.
+ */
+interface DeviceAppProcess {
+  id: string;
+  state: (typeof APP_PROCESS_STATES)[number];
+}
+/**
+ * A linked worktree's `git status`. `changed` counts tracked paths with staged or unstaged changes, including
+ * conflicts; `untracked` counts untracked entries as `git status` lists them, so an untracked directory counts once.
+ * `ahead` and `behind` compare HEAD with `upstream`, and are null when there is no upstream or it no longer exists.
+ * `mergedInto` names the default branch (`origin/main`) when `gc` would consider the branch merged into it, judged
+ * from local refs without fetching.
+ */
+interface WorktreeGit {
+  changed: number;
+  untracked: number;
+  upstream: string | null;
+  ahead: number | null;
+  behind: number | null;
+  mergedInto: string | null;
+}
+/**
+ * The GitHub pull request of a worktree's branch and HEAD, as `status --watch` last looked it up through `gh`.
+ * `state` is `draft` for an open draft. `checks` counts the head commit's check runs and commit statuses, null when it
+ * has none. `checkedAt` is when Stim last asked GitHub.
+ */
+interface WorktreePullRequest {
+  number: number;
+  url: string;
+  title: string;
+  state: "open" | "draft" | "merged" | "closed";
+  checks: {
+    passing: number;
+    failing: number;
+    pending: number;
+  } | null;
+  reviewDecision: "approved" | "changes-requested" | "review-required" | null;
+  checkedAt: string;
+}
+interface WorktreeFacts {
+  path: string;
+  branch?: string;
+  repository?: string;
+  /** Null when git could not be read in time, or the worktree is in a folder status does not open. */
+  git?: WorktreeGit | null;
+  /** Null when GitHub has no pull request for the branch; absent when unknown, such as without `gh`. */
+  pullRequest?: WorktreePullRequest | null;
+  /** Present with `git`: what the worktree's git chip shows, from `gitChip`. */
+  gitChip?: GitChip;
+}
+/** Every coding-agent tool whose sessions status can attribute to an environment. */
+declare const AGENT_TOOLS: readonly ["claude-code", "codex"];
+type AgentTool = (typeof AGENT_TOOLS)[number];
+/**
+ * A coding-agent session working in an environment: one whose working directory `cwd` is the environment's path,
+ * inside it, or its git worktree root, or one that ran a Stim command in it. `title` is the short name the tool keeps
+ * for the session, never its conversation. `lastActiveAt` is the tool's own last update, or the Stim command's time
+ * when that is newer. `openUrl` opens the session in the tool's desktop app when that app is installed on this Mac.
+ * `webUrl` opens a Claude Code session with Remote Control connected on claude.ai/code or in the Claude mobile app.
+ */
+interface AgentSession {
+  tool: AgentTool;
+  sessionId: string;
+  title?: string;
+  cwd: string;
+  startedAt?: string;
+  lastActiveAt?: string;
+  pid?: number;
+  openUrl?: string;
+  webUrl?: string;
+}
+/**
+ * An agent session that stopped running in an environment, with the details Stim last found while it ran. `endedAt`
+ * is the last time a status watcher found it running.
+ */
+interface EndedAgentSession extends Omit<AgentSession, "pid"> {
+  endedAt: string;
+}
+interface AndroidRuntimeFacts {
+  serial: string | null;
+  state: "detected" | "not-detected" | "missing" | "unknown";
+  error?: string;
+}
+/** Every connection state a physical device can report. */
+declare const PHYSICAL_DEVICE_CONNECTIONS: readonly ["connected", "disconnected", "unknown"];
+type PhysicalDeviceConnection = (typeof PHYSICAL_DEVICE_CONNECTIONS)[number];
+/**
+ * A physical iPhone, iPad or Android phone the workspace holds an unexpired lease on, from `ios --device`,
+ * `android --device` or `device lock`. Stim uses it and never owns it, so `owned` is always false. `id` is the
+ * UDID or adb serial. `name` is the device's own name, falling back to the name the lease recorded; `model` is the
+ * marketing name devicectl reports, null when it could not be read, or the Android model the lease recorded.
+ * `connection` is `connected` when devicectl can reach the phone or adb lists it as `device`, `disconnected` when
+ * the tool answered without it, and `unknown` when the tool could not be read in time. `lease.holder` is the
+ * workspace path that holds it.
+ */
+interface PhysicalDeviceState {
+  platform: StatsPlatform;
+  slot: string;
+  id: string;
+  name: string | null;
+  model: string | null;
+  owned: false;
+  physical: true;
+  connection: PhysicalDeviceConnection;
+  lease: {
+    holder: string;
+    kind: "declared" | "run";
+    grantedAt: string | null;
+    expiresAt: string;
+  };
+}
+interface RemoteDeviceState {
+  platform: "ios" | "android" | null;
+  backend: "eas";
+  sessionId: string;
+  state: "claimed" | "unclaimed" | "unknown";
+  startedAt: string | null;
+  webPreviewUrl: string | null;
+}
+/**
+ * One part of a worktree's git chip, in display order: commits ahead of and behind the upstream, uncommitted files
+ * (changed plus untracked), the base branch the branch is merged into (left out when its pull request is merged,
+ * whose own mark says so), and a branch with no upstream that is not merged.
+ */
+type GitChipPart = {
+  kind: "arrows";
+  ahead: number;
+  behind: number;
+} | {
+  kind: "changed";
+  count: number;
+} | {
+  kind: "merged";
+  into: string;
+} | {
+  kind: "no-upstream";
+};
+/** A pull request's checks at a glance: any failing, else any pending, else any passing; null without checks. */
+type ChecksState = "passing" | "failing" | "pending" | null;
+interface GitChip {
+  parts: GitChipPart[];
+  ci: ChecksState;
+}
+/**
+ * Whether a running owned simulator or emulator lacks the workspace's app: `none` when its platform never built
+ * successfully here and the latest build failed, `closed` when status saw no app process, else null.
+ */
+type AppPresence = "none" | "closed" | null;
+declare const WORKSPACE_STAGE_KINDS: readonly ["building", "warming", "ready", "build-failed", "running", "stopped"];
+/**
+ * Where a workspace is, first match wins: `building` while a build runs, `warming` and `ready` from `phase` when
+ * nothing is live, `build-failed` when the newest run of either platform failed, `running` when it is live or holds
+ * a remote device, else `stopped`. `since` is when that began: the build's start, the warm phase's time, the failed
+ * run's end (else start), the supervisor's start, or Metro's last stop. `platform` names the build for `building`
+ * and `build-failed`. `closedApps` lists, for `running`, the devices whose `appPresence` is `closed`.
+ */
+interface WorkspaceStage {
+  kind: (typeof WORKSPACE_STAGE_KINDS)[number];
+  since: string | null;
+  platform: StatsPlatform | "macos" | null;
+  closedApps: {
+    platform: StatsPlatform;
+    slot: string;
+  }[];
+}
+/** Every code a status issue can carry. */
+declare const STATUS_ISSUE_CODES: readonly ["port-not-ours", "sim-missing", "sim-without-metro", "avd-serial-changed", "avd-missing", "avd-not-detected", "avd-unchecked", "android-reverse-missing", "supervisor-unverified", "browser-unverified", "browser-orphaned"];
+type StatusIssueCode = (typeof STATUS_ISSUE_CODES)[number];
+/**
+ * One thing in a workspace that needs the user, or with severity `info` a note that needs nothing. `remedy` is a
+ * command to run from `workspace`; `slot` is absent for the default device slot. `warnings` carries the `error` and
+ * `warning` issues as text.
+ *
+ * Severity:
+ * - `error`: Stim cannot verify or safely act on something; a person resolves it, following the teardown guide.
+ * - `warning`: something is broken now and needs someone to act, such as an app that cannot reach Metro, a held
+ *   port or a device that vanished while expected.
+ * - `info`: a fact the next normal Stim command handles by itself, so it needs no action.
+ *
+ * The phone app and Stim Desktop show `error` and `warning` and hide `info`; plain `stim status` prints `info` as a
+ * dim note with no remedy.
+ */
+interface StatusIssue {
+  code: StatusIssueCode;
+  severity: "error" | "warning" | "info";
+  message: string;
+  remedy: string;
+  workspace: string;
+  slot?: string;
+}
+/** Every state the owned page's latest load can report. */
+declare const WEB_PAGE_STATES: readonly ["loading", "loaded", "failed"];
+/**
+ * The owned page's latest load, from the page-load marker in the workspace's web log: `url` is the document it
+ * loaded, `state` is `failed` when that document did not load or the page crashed, with the log message as
+ * `error`. `route`, present only when an in-app route change (history API or fragment) moved the page off `url`
+ * since the load, is the URL it shows now.
+ */
+interface WebPageState {
+  url: string;
+  state: (typeof WEB_PAGE_STATES)[number];
+  error?: string;
+  route?: string;
+}
+/**
+ * The workspace's Stim-owned Chrome. `pid` is Chrome's process and `supervisorPid` the Stim process that holds
+ * its DevTools session. `cdpEndpoint` is the loopback DevTools HTTP endpoint agents can attach to, and `targetId`
+ * the DevTools target of the owned page; both are null when the browser is not running. `profile` is the
+ * Stim-owned user data directory. `page` is null before the page's first load. `activity` names DevTools clients
+ * other than Stim's as drivers.
+ */
+interface WebBrowserState {
+  browser: "chrome";
+  version: string | null;
+  running: boolean;
+  pid: number | null;
+  supervisorPid: number | null;
+  url: string;
+  headless: boolean;
+  viewport: WebViewport;
+  profile: string;
+  cdpEndpoint: string | null;
+  targetId: string | null;
+  page?: WebPageState | null;
+  activity?: DeviceActivity;
+}
+/** The steps of `stim worktree warm`: `refresh` fast-forwards and installs in the source checkout, `copy` carries ignored entries. */
+type WarmStep = "refresh" | "copy";
+/**
+ * Where a workspace is in its lifecycle: `warming` while `stim worktree warm` runs in it, `ready` after a warm
+ * succeeded and before any `start`, `ios`, `android`, `web` or `reload` there, for at most two hours; `live` when
+ * anything it owns runs, else `idle`.
+ */
+declare const WORKSPACE_PHASES: readonly ["warming", "ready", "live", "idle"];
+type WorkspacePhase = (typeof WORKSPACE_PHASES)[number];
+/** A folder's size on disk as `status --watch` last measured it. */
+interface DiskMeasure {
+  bytes: number;
+  measuredAt: string;
+}
+/**
+ * An environment's disk use as `status --watch` last measured it. `worktreeBytes` is the git worktree folder, or the
+ * workspace folder outside one, node_modules included. `nodeModulesBytes` is node_modules at the worktree root and,
+ * when different, at the workspace path, and is part of `worktreeBytes`. `buildBytes` is Stim's own folder for the
+ * workspace: Xcode derived data, Gradle outputs and logs. A figure is null until it was measured; `measuredAt` is the
+ * oldest measurement.
+ */
+interface EnvironmentDisk {
+  worktreeBytes: number | null;
+  nodeModulesBytes: number | null;
+  buildBytes: number | null;
+  measuredAt: string;
+}
+/**
+ * A Metro bundle request: `bundling` while one is in flight on the workspace's Metro, with its `platform`,
+ * `startedAt` and, when Metro reported progress for it, `percent` (0-100). `last` is the newest finished request,
+ * `durationMs` from request to response end.
+ */
+interface MetroBundleState {
+  bundling: boolean;
+  platform?: StatsPlatform;
+  startedAt?: string;
+  percent?: number;
+  last?: {
+    platform: StatsPlatform;
+    status: "ok" | "failed";
+    durationMs: number;
+    finishedAt: string;
+  };
+}
+interface SimulatorState {
+  name: string | null;
+  udid: string;
+  owned: boolean;
+  state: string;
+  activity?: DeviceActivity;
+  app?: DeviceAppProcess;
+  appPresence?: AppPresence;
+  /** The simulator's data folder, for an owned simulator once measured. */
+  disk?: DiskMeasure;
+  /** Present while the device is not booted after the supervisor shut it down for `devices.idleShutdownMinutes`. */
+  idleShutdown?: DeviceIdleShutdownRecord;
+}
+interface AndroidDeviceState {
+  name: string | undefined;
+  owned: boolean;
+  physical: boolean;
+  serial?: string | null;
+  state?: AndroidRuntimeFacts["state"];
+  deviceProfile?: string | null;
+  activity?: DeviceActivity;
+  app?: DeviceAppProcess;
+  appPresence?: AppPresence;
+  /** The AVD's folder, for an owned emulator once measured. */
+  disk?: DiskMeasure;
+  /** Present while the emulator is not running after the supervisor shut it down for `devices.idleShutdownMinutes`. */
+  idleShutdown?: DeviceIdleShutdownRecord;
+}
+interface EnvironmentState {
+  slots?: {
+    slot: string;
+    ios: SimulatorState | null | undefined;
+    android: AndroidDeviceState | null | undefined;
+  }[];
+  path: string;
+  live: boolean;
+  phase?: WorkspacePhase;
+  /** When the warm started (`warming`) or finished (`ready`); null for `live` and `idle`. */
+  phaseSince?: string | null;
+  /** Whether stim-server may record this workspace's device screens, from `recording.enabled`. */
+  recording?: {
+    enabled: boolean;
+  };
+  /** Where the workspace is, from `workspaceStage`; `stim status --json` always sets it. */
+  stage?: WorkspaceStage;
+  /** The step a `warming` workspace's warm is in; absent in every other phase. */
+  warmStep?: WarmStep;
+  /**
+   * The memory this workspace's processes use, as `memorySource` says: the sum of its `machine` owners' `memoryMb`
+   * when status read their footprints, or else a fixed estimate per booted simulator, detected emulator, running
+   * Metro and running Chrome. `capacity.committedMb` sums it.
+   */
+  memoryMb: number;
+  /** How `memoryMb` was obtained; absent from payloads written before it existed, which carry the estimate. */
+  memorySource?: Exclude<MemorySource, "rss">;
+  warnings: string[];
+  issues: StatusIssue[];
+  ios?: SimulatorState | null;
+  android?: AndroidDeviceState | null;
+  metro?: {
+    port: number;
+    running: boolean;
+    pid: number | null;
+    tunnel?: {
+      provider: Exclude<TunnelMode, "auto" | "off" | "expo">;
+      url: string;
+    };
+    idleStop?: IdleStopRecord;
+    lastStop?: MetroLastStop;
+    /** The other process that answers Metro on `port`; `cwd` is null when its directory could not be read. */
+    heldBy?: {
+      pid: number;
+      cwd: string | null;
+    };
+    /** Absent when the Metro log holds no bundle request. */
+    bundle?: MetroBundleState;
+  } | null;
+  web?: WebBrowserState | null;
+  macos?: MacosAppState | null;
+  supervisor?: {
+    pid: number | null;
+    mode: string | null;
+    startedAt: string | null;
+    healthy: boolean;
+  } | null;
+  logs?: {
+    dir: string;
+    errorsSinceMarker: number;
+  } | null;
+  worktree?: WorktreeFacts | null;
+  remoteDevices?: RemoteDeviceState[];
+  /** The physical devices this workspace leases, in every slot; absent when it leases none. */
+  physicalDevices?: PhysicalDeviceState[];
+  build?: BuildReport | null;
+  lastBuilds?: Partial<Record<StatsPlatform, LastBuildReport>>;
+  /** Each platform's recent runs, newest first, at most `BUILD_HISTORY_LIMIT` each. */
+  builds?: Partial<Record<StatsPlatform, BuildHistoryEntry[]>>;
+  disk?: EnvironmentDisk;
+  /** The coding-agent sessions working in the environment, most recently active first; absent when none. */
+  agents?: AgentSession[];
+  /** The agent sessions that stopped running here in the last 3 days, most recently ended first; absent when none. */
+  endedAgents?: EndedAgentSession[];
+}
+/** `committedMb` sums the environments' `memoryMb`; `overCapacity` is that sum over 60% of `totalMemoryMb`. */
+interface StatusCapacity {
+  liveCount: number;
+  committedMb: number;
+  totalMemoryMb: number;
+  overCapacity: boolean;
+}
+interface DeviceLeaseState {
+  slot?: string;
+  path: string;
+  platform: string;
+  id: string | null;
+  deviceName: string | null;
+  holder: string | null;
+  grantedAt: string | null;
+  expiresAt: string | null;
+  mine: boolean;
+  expired: boolean;
+  parsed: boolean;
+}
+/**
+ * Where a memory figure comes from. `footprint` is each process's physical footprint, which Activity Monitor's Memory
+ * column shows. `rss` sums resident set sizes, which count pages shared between processes once per process, so a
+ * simulator reports well above its footprint; the machine owners fall back to it when the footprint helper cannot be
+ * built. `estimate` is a fixed amount per running thing, which an environment reports whenever it has no footprint.
+ */
+declare const MEMORY_SOURCES: readonly ["footprint", "rss", "estimate"];
+type MemorySource = (typeof MEMORY_SOURCES)[number];
+/** Every kind of process owner the status machine section reports. */
+declare const MACHINE_OWNER_KINDS: readonly ["simulator", "emulator", "metro", "build", "browser", "macos", "server", "shared"];
+type MachineOwnerKind = (typeof MACHINE_OWNER_KINDS)[number];
+/**
+ * One thing using this Mac's CPU and memory now. Each process is counted in exactly one owner: the one whose root
+ * process is its nearest ancestor. `workspace` and `slot` (absent for the default slot) name the workspace a
+ * simulator, emulator, Metro, build or Chrome belongs to; a device no workspace records has a null workspace, and
+ * machine-wide processes are `shared`. `id` is the simulator's UDID, the emulator's AVD name, Metro's port as text,
+ * the build's platform, or null. `owned` is true only for what Stim started and stops: a workspace's owned device,
+ * Metro, build or Chrome. `cpuPercent` is `ps` %CPU summed over the owner's processes, where 100 is one core.
+ * `residentMb` sums their resident set sizes; pages shared between processes count once per process, so a
+ * simulator, whose processes all map the runtime's shared libraries, reports well above its physical footprint.
+ * `memoryMb` sums their physical footprints when `MachineUsageState.memorySource` is `footprint`, taking the resident
+ * size of a process the footprint helper could not read, and equals `residentMb` when it is `rss`.
+ */
+interface MachineOwner {
+  kind: MachineOwnerKind;
+  name: string;
+  workspace: string | null;
+  slot?: string;
+  id: string | null;
+  owned: boolean;
+  cpuPercent: number;
+  residentMb: number;
+  memoryMb: number;
+  processes: number;
+}
+/** Where this machine's CPU and memory go, from one pass over the host process table. */
+interface MachineUsageState {
+  memorySource: Exclude<MemorySource, "estimate">;
+  owners: MachineOwner[];
+}
+/** The payload `stim status --json` prints, and `status --watch --json` prints on each change. */
+interface StatusPayload {
+  environments: (EnvironmentState & {
+    labelOnly?: true;
+  })[];
+  capacity: StatusCapacity;
+  deviceLeases: DeviceLeaseState[];
+  unprovisionedWorktrees: WorktreeFacts[];
+  simctlAvailable: boolean;
+  /** Null when nothing runs that status attributes, so it read no process table, or when the table was unreadable. */
+  machine: MachineUsageState | null;
+}
+//#endregion
+//#region state/status-derived.d.ts
+declare function withGitChip(worktree: WorktreeFacts): WorktreeFacts;
+/** The environment with the conclusions clients draw from it: `stage`, `appPresence`, `gitChip` and `cause`. */
+declare function withDerivedFacts<T extends EnvironmentState>(env: T): T;
+//#endregion
+//#region state/status-measures.d.ts
+/** The file that caches `path`'s measured size, one file per folder. */
+declare function diskUsageCacheFile(path: string): string;
+/** The file that caches the pull request of the worktree at `path`. */
+declare function pullRequestCacheFile(path: string): string;
+/** One file of the disk-usage or pull-request cache. */
+interface StatusCacheEntry {
+  kind: "disk-usage" | "pull-request";
+  file: string;
+  /** The folder or worktree the file caches, or null when the file does not record one under its own name. */
+  path: string | null;
+  bytes: number;
+}
+/** Every finished file in the disk-usage and pull-request caches; a file being written is not listed. */
+declare function listStatusCacheEntries(): StatusCacheEntry[];
+/** A worktree's cached pull request lookup: the branch and HEAD it was looked up for, and when. */
+interface PullRequestCacheEntry {
+  path: string;
+  branch: string;
+  head: string;
+  checkedAt: string;
+  pullRequest: WorktreePullRequest | null;
+}
+/** The cached pull request lookup of the worktree at `path`, or null before one succeeded. */
+declare function readPullRequestCache(path: string): PullRequestCacheEntry | null;
+/** The cached size of the folder at `path`, or null before it was measured. */
+declare function readDiskUsage(path: string): DiskMeasure | null;
+/** The running build's tool detail its process last wrote, when the file belongs to the build with `claimId`. */
+declare function readBuildDetail(root: string, claimId: string): BuildDetail | null;
+/** The coding-agent sessions `status --watch` last found running on this Mac, and when it looked. */
+interface AgentSessionsCache {
+  discoveredAt: string;
+  sessions: AgentSession[];
+}
+/** An agent session as Stim wrote it to its cache or workspace state, or null when it is not one. */
+declare function agentSessionOf(value: unknown): AgentSession | null;
+/** How long a workspace keeps an agent session after it stopped running. */
+declare const ENDED_AGENT_RETENTION_MS: number;
+/** An ended agent session as Stim wrote it, or null when it is not one. */
+declare function endedAgentSessionOf(value: unknown): EndedAgentSession | null;
+/** The workspace's agent sessions that ended within `ENDED_AGENT_RETENTION_MS` of `now`, most recently ended first. */
+declare function readEndedAgentSessions(root: string, now: number): EndedAgentSession[];
+/** The agent sessions `status --watch` last cached, or null before it cached any. */
+declare function readAgentSessionsCache(): AgentSessionsCache | null;
+//#endregion
+//#region state/stim-build.d.ts
+/**
+ * A digest of Stim's built code: the first 16 hex characters of the sha256 over the sorted `*.mjs` names and
+ * bytes of a `stim` `dist` directory. A client and a build machine offload only when both compute the same one.
+ */
+declare function stimBuildDigest(dir: string): string | null;
+//#endregion
+//#region state/viewers.d.ts
+interface ViewedDevice {
+  platform: "ios" | "android";
+  /** The simulator UDID or the emulator serial. */
+  id: string;
+}
+/** A stim-server's viewer record: the devices it streams frames of, and the server's process identity. */
+interface DeviceViewersRecord {
+  pid: number;
+  processToken: string;
+  devices: ViewedDevice[];
+}
+/**
+ * The devices a running stim-server streams frames of. A record whose server is not proven to be the same live
+ * process counts for nothing.
+ */
+declare function readViewedDevices(dir?: string): ViewedDevice[];
+//#endregion
+//#region state/stats.d.ts
+declare const STATS_VERSION = 1;
+interface StatsBucket {
+  runs: number;
+  failed: number;
+  hits: number;
+  misses: number;
+  coldRuns: number;
+  coldRunMs: number;
+  hitRuns: number;
+  hitRunMs: number;
+  timeSavedMs: number;
+  firstRunAt: string;
+  lastRunAt: string;
+  lastColdBuildMs?: number;
+  lastPodsMs?: number;
+  offloadedRuns?: number;
+  offloadedRunMs?: number;
+  lastOffloadHost?: string;
+}
+type StatsScope = Partial<Record<StatsPlatform, StatsBucket>>;
+interface RunSample {
+  at: string;
+  durationMs: number;
+  phases: Record<string, number>;
+  /** Whether the run created, adopted or cold-booted its device; absent on samples recorded before the tag. */
+  deviceSetup?: boolean;
+}
+type RunHistory = Partial<Record<StatsPlatform, Partial<Record<RunOutcomeKind, RunSample[]>>>>;
+/** Where a compiling build ran: here, on a build machine, or here after offloading it failed. */
+declare const PLACEMENT_DECISIONS: readonly ["here", "offloaded", "fell-back"];
+type PlacementDecision = (typeof PLACEMENT_DECISIONS)[number];
+interface StatsPlacement {
+  at: string;
+  project: string;
+  platform: StatsPlatform;
+  decision: PlacementDecision;
+  reason: string;
+  machine?: string;
+  buildMs?: number;
+  /** The project's last cold build here before this run. */
+  localEstimateMs?: number;
+  failed?: true;
+}
+interface BuildMachineTotals {
+  offloaded: number;
+  offloadedMs: number;
+  /** Sum of local estimate minus offloaded build time, over offloaded builds that had an estimate; can be negative. */
+  savedMs: number;
+  fallbacks: number;
+  lastOffloadAt?: string;
+  lastFallbackAt?: string;
+}
+interface StatsRecord {
+  version: number;
+  machine: StatsScope;
+  projects: Record<string, StatsScope>;
+  history?: Record<string, RunHistory>;
+  placements?: StatsPlacement[];
+  buildMachines?: Record<string, BuildMachineTotals>;
+}
+/**
+ * The two phase durations a run reads back to size its own heartbeat: the
+ * project's last cold build and its last `pod install`, in milliseconds.
+ */
+interface RunEstimates {
+  coldBuildMs: number | null;
+  podsMs: number | null;
+}
+interface ReadStatsResult {
+  record: StatsRecord | null;
+  note: string | null;
+}
+declare const HISTORY_LIMIT = 10;
+declare function statsProjectKey({ root, commonDir, repoRoot }: {
+  root: string;
+  commonDir: string | null;
+  repoRoot: string | null;
+}): string;
+interface BuildMachineDay {
+  offloaded: number;
+  offloadedMs: number;
+  savedMs: number;
+  fallbacks: number;
+}
+interface OffloadSummary {
+  today: {
+    here: number;
+    offloaded: number;
+    fellBack: number;
+  };
+  machines: Record<string, {
+    today: BuildMachineDay;
+    total: BuildMachineTotals;
+  }>;
+  /** Newest first. */
+  placements: StatsPlacement[];
+}
+/** Placement counts for the local calendar day of `now`, per-machine totals, and the retained placements. */
+declare function offloadSummary(record: StatsRecord | null, now: number): OffloadSummary;
+declare function trimSamples(samples: RunSample[]): RunSample[];
+declare function readStats(): ReadStatsResult;
+declare function readRunEstimates({ projectKey, platform, read }: {
+  projectKey: string | null;
+  platform: StatsPlatform;
+  read?: () => ReadStatsResult;
+}): RunEstimates;
+declare function wholePhases(phases: unknown): Record<string, number>;
+declare function decodeStats(text: string): {
+  record: StatsRecord | null;
+  newerVersion: number | null;
+};
+interface StatsReport {
+  version: number;
+  project: ({
+    key: string;
+  } & StatsReport["machine"]) | null;
+  machine: {
+    ios: StatsBucket | null;
+    android: StatsBucket | null;
+  };
+  offload: OffloadSummary;
+}
+declare function readStatsReport(key: string | null, now: number): {
+  report: StatsReport;
+  note: string | null;
+};
+declare function findProjectRoot(startDir: string): string | null;
+//#endregion
+//#region state/device-host.d.ts
+type HostedDevicePlatform = "ios" | "android" | "macos";
+interface HostedIosChoice {
+  deviceTypeId: string;
+  runtimeId: string;
+  deviceType: string;
+  runtime: string;
+  architecture: "arm64" | "x86_64";
+}
+interface HostedIosDevice extends HostedIosChoice {
+  udid: string;
+  name: string;
+}
+interface HostedAndroidChoice {
+  systemImage: string;
+  deviceProfile: string;
+  architecture: "arm64-v8a" | "x86_64";
+}
+interface HostedAndroidDevice extends HostedAndroidChoice {
+  avdName: string;
+  serial: string;
+  consolePort: number;
+}
+type HostedDevice = HostedIosDevice | HostedAndroidDevice | HostedMacosDevice;
+interface HostedDeviceSelectors {
+  deviceType?: string;
+  runtime?: string;
+  systemImage?: string;
+  deviceProfile?: string;
+}
+interface HostedDeviceOfferRequest extends HostedDeviceSelectors {
+  platform: HostedDevicePlatform;
+}
+type HostedNativeOffer = {
+  resources: {
+    cpus: number;
+    /** Five-minute system load divided by available CPU count. */
+    loadPerCore: number;
+    memoryFreeBytes: number;
+    memoryPressure: "normal" | "warning" | "critical" | null;
+    /** Available bytes on the Stim home volume, not necessarily the Android AVD volume. */
+    workerDiskFreeBytes: number | null;
+  };
+  declined: string | null;
+} & ({
+  platform: "ios";
+  choice: HostedIosChoice | null;
+} | {
+  platform: "android";
+  choice: HostedAndroidChoice | null;
+} | {
+  platform: "macos";
+  choice: HostedMacosChoice | null;
+});
+type HostedDeviceOffer = HostedNativeOffer & {
+  capacity: {
+    running: number;
+    max: number;
+    available: number | null;
+  };
+};
+interface HostedDeviceRequest extends HostedDeviceOfferRequest {
+  workspace: string;
+  slot: string;
+  attempt: string;
+}
+type HostedDevicePhase = "preparing" | "ready" | "stopping" | "stopped" | "unknown";
+interface HostedDeviceSession extends HostedDeviceRequest {
+  id: string;
+  client: string;
+  state: HostedDevicePhase;
+  device: HostedDevice | null;
+  consolePort?: number;
+  appSlot?: number;
+  createdAt: string;
+  notice?: string;
+  appAttempt?: string;
+  metroPort?: number;
+}
+declare function deviceHostRoot(): string;
+declare function deviceHostArea(id: string): string;
+declare function parseHostedChoice(value: unknown): HostedIosChoice | null;
+declare function parseHostedDevice(value: unknown): HostedIosDevice | null;
+declare function parseHostedAndroidDevice(value: unknown): HostedAndroidDevice | null;
+/** Android Emulator -help-port defines the supported even console ports as 5554 through 5584. */
+declare function hostedConsolePort(value: unknown): value is number;
+declare function parseHostedPlatformDevice(value: unknown, platform: HostedDevicePlatform): HostedDevice | null;
+declare function hostedDeviceId(device: HostedDevice): string;
+declare function parseHostedRequest(value: unknown): HostedDeviceRequest | null;
+declare function parseHostedOfferRequest(value: unknown): HostedDeviceOfferRequest | null;
+declare function parseHostedNativeOffer(value: unknown): HostedNativeOffer | null;
+/** A missing established journal or malformed record is a refusal, never an empty reservation set. */
+declare function readHostedSessions(): HostedDeviceSession[];
+/** The private worker's exact device record; an absent record is unresolved after creation started. */
+declare function readHostedDevice(home: string): HostedIosDevice;
+declare function readHostedDevice(home: string, platform: "android"): HostedAndroidDevice;
+declare function readHostedDevice(home: string, platform: "macos"): HostedMacosDevice;
+declare function readHostedDevice(home: string, platform: HostedDevicePlatform): HostedDevice;
+/** Hosted sessions use isolated homes: only one exact device of their platform may appear in this ledger. */
+declare function assertHostedDeviceLedger(home: string, id: string, platform?: HostedDevicePlatform): void;
+//#endregion
+//#region state/device-host-machines.d.ts
+/** A separately approved hosting machine, pinned before sending its device token. */
+interface DeviceHostMachineCredential {
+  machine: string;
+  nodeId: string;
+  dnsName: string;
+  deviceId: string;
+  deviceToken: string;
+  state: "pending" | "approved";
+  requestedAt: string;
+}
+/** An absent store is empty; unreadable or malformed credentials refuse access without discarding pins. */
+declare function readDeviceHostMachines(): DeviceHostMachineCredential[];
+//#endregion
+//#region state/tailnet.d.ts
+interface TailnetPeer {
+  nodeId: string;
+  dnsName: string;
+  /** A tailnet address of the node; WireGuard delivers packets to it only from that node. */
+  address: string;
+}
+declare function parseMachine(entry: string): {
+  name: string;
+  port: number;
+} | null;
+/**
+ * The one peer in `tailscale status --json` whose MagicDNS name is `name` or starts with `name.`. `ID` there is
+ * the node's StableID, the same value `tailscale whois` reports as `Node.StableID`.
+ */
+declare function findPeer(status: unknown, name: string): TailnetPeer | "missing" | "ambiguous";
+interface Endpoint {
+  url: string;
+  servername: string;
+  host: string;
+}
+/**
+ * Connects to the pinned node's own tailnet address rather than resolving its name, so the socket reaches the
+ * node whose ID was just checked. `tailscale serve` still needs the MagicDNS name for TLS (SNI and certificate)
+ * and for its Host routing.
+ */
+declare function endpoint(peer: TailnetPeer, port: number): Endpoint;
+/**
+ * The endpoint of a paired machine's pinned node, or why Stim does not connect to it. The name must still
+ * resolve to exactly the pinned node; the token is never sent anywhere else.
+ */
+declare function pinnedEndpoint(credential: {
+  machine: string;
+  nodeId: string;
+}, current: unknown): Endpoint | string;
+//#endregion
+//#region state/hosted-logs.d.ts
+type HostedLogsCursor = Record<string, number>;
+interface HostedLogsPage {
+  records: NdjsonRecord[];
+  cursor: HostedLogsCursor;
+  /** True when the budget ended this page before the end of the logs; ask again with `cursor`. */
+  more: boolean;
+}
+declare const HOSTED_LOGS_PAGE_BYTES: number;
+declare const HOSTED_LOGS_FIRST_BYTES: number;
+declare function parseHostedLogsCursor(value: unknown): HostedLogsCursor | null;
+declare function hostedMacosLogsDir(home: string): string | null;
+/**
+ * The records in `dir` after `cursor`, in file order. A file without a cursor entry starts at most
+ * {@link HOSTED_LOGS_FIRST_BYTES} before its end. A file that shrank since the cursor was taken was rotated: the end of
+ * its previous generation is read first, and only as much of it as the page budget allows.
+ */
+declare function readLogsSince(dir: string, cursor: HostedLogsCursor): HostedLogsPage;
+//#endregion
+export { StatsPlacement as $, levelRank as $a, configLockPath as $i, DevServerStopRequest as $n, hostedAppAttempt as $r, BuildPhase as $t, deviceHostArea as A, workspaceStateFile as Aa, expectedShape as Ai, STATUS_ISSUE_CODES as An, DeviceRecord as Ao, readMacosRecord as Ar, withDerivedFacts as At, parseHostedRequest as B, followLogs as Ba, RecordingPlatform as Bi, WarmStep as Bn, MachineCapacity as Bo, HostedMacosPlacement as Br, AndroidDeviceState as Bt, HostedDeviceRequest as C, workspaceEndedAgentsFile as Ca, SettingsPayload as Ci, NativeBuildStep as Cn, getProjectSettings as Co, MacosAppRecord as Cr, listStatusCacheEntries as Ct, HostedIosDevice as D, workspaceLogsDir as Da, WebViewport as Di, PlannedPhase as Dn, withConfigLock as Do, macosAppState as Dr, readDiskUsage as Dt, HostedIosChoice as E, workspaceLogErrorIndex as Ea, WEB_VIEWPORTS as Ei, PhysicalDeviceState as En, loadConfig as Eo, MacosProcess as Er, readBuildDetail as Et, parseHostedChoice as F, attachExpoErrorContext as Fa, RECORDING_CAP_BYTES as Fi, StatusIssueCode as Fn, SettingsObject as Fo, HostedAgentGrant as Fr, ActiveBuildState as Ft, OffloadSummary as G, readLogRecords as Ga, listSegments as Gi, WorktreeFacts as Gn, tryAcquireBuildSlotClaim as Go, parseHostedMacosDevice as Gr, BuildCacheHit as Gt, readHostedSessions as H, markerWindow as Ha, closedSegmentName as Hi, WebPageState as Hn, buildSlotsDir as Ho, hostedMacosBundleId as Hr, AppPresence as Ht, parseHostedDevice as I, buildCriteria as Ia, RECORDING_FOOTAGE_MS as Ii, StatusPayload as In, StimConfig as Io, HostedAgentLease as Ir, ActivityDriver as It, RunEstimates as J, tailRead as Ja, recordingDeviceName as Ji, BUILD_HISTORY_KEY as Jn, HostedAppDelivery as Jr, BuildDiagnostic as Jt, PLACEMENT_DECISIONS as K, recordMatches as Ka, openSegmentName as Ki, WorktreeGit as Kn, parseHostedMacosPlacement as Kr, BuildCause as Kt, parseHostedNativeOffer as L, bundleMarkerPlatform as La, RECORDING_PLATFORMS as Li, WEB_PAGE_STATES as Ln, SupervisorRecord as Lo, HostedAppLaunch as Lr, ActivityRecencyBasis as Lt, hostedConsolePort as M, ERROR_SOURCES as Ma, isSensitiveReference as Mi, StatsPlatform as Mn, PlatformRecords as Mo, HOSTED_MACOS_APP_SLOTS as Mr, ACTIVITY_RECENCY_BASES as Mt, hostedDeviceId as N, QueryCriteria as Na, settingDefinition as Ni, StatusCapacity as Nn, ProjectRecord as No, HostedAgentAccess as Nr, AGENT_TOOLS as Nt, HostedNativeOffer as O, workspaceMetadataFile as Oa, acceptsShape as Oi, RemoteDeviceState as On, ConcurrencyLimits as Oo, parseMacosRecord as Or, readEndedAgentSessions as Ot, parseHostedAndroidDevice as P, advanceTail as Pa, settingValueError as Pi, StatusIssue as Pn, RepoRecord as Po, HostedAgentDriverName as Pr, APP_PROCESS_STATES as Pt, StatsBucket as Q, SOURCES as Qa, buildMachinesLock as Qi, DevServerStopRecord as Qn, hostedAppArea as Qr, BuildMissReason as Qt, parseHostedOfferRequest as R, compileGrep as Ra, RecordedDevice as Ri, WORKSPACE_PHASES as Rn, BuildMachineCredential as Ro, HostedMacosChoice as Rr, AgentSession as Rt, HostedDevicePlatform as S, workspaceDerivedData as Sa, SettingType as Si, NATIVE_BUILD_STEPS as Sn, getProjectSetting as So, workspaceLastUsed as Sr, endedAgentSessionOf as St, HostedDeviceSession as T, workspaceGradleBuild as Ta, TunnelMode as Ti, PhysicalDeviceConnection as Tn, isPathPrefix as To, MacosBuild as Tr, readAgentSessionsCache as Tt, BuildMachineTotals as U, parseSince as Ua, footageDrops as Ui, WorkspacePhase as Un, machineCapacity as Uo, parseHostedAgentGrant as Ur, BUILD_PHASES as Ut, readHostedDevice as V, logFiles as Va, capDrops as Vi, WebBrowserState as Vn, buildSlotPath as Vo, hostedMacosAppSlot as Vr, AndroidRuntimeFacts as Vt, HISTORY_LIMIT as W, queryLogs as Wa, listRecordedDevices as Wi, WorkspaceStage as Wn, saturation as Wo, parseHostedMacosChoice as Wr, BUILD_RESULTS as Wt, RunSample as X, LEVELS as Xa, agentSessionsCacheFile as Xi, DEVICE_IDLE_SHUTDOWN_KEY as Xn, HostedAppOffer as Xr, BuildMissCategory as Xt, RunHistory as Y, countErrorEntries as Ya, recordingEnabled as Yi, BUILD_HISTORY_LIMIT as Yn, HostedAppFile as Yr, BuildHistoryEntry as Yt, STATS_VERSION as Z, NdjsonRecord as Za, buildMachinesFile as Zi, DEV_SERVER_STOP_REQUEST_KEY as Zn, HostedAppRecord as Zr, BuildMissChange as Zt, HostedAndroidDevice as _, sharedPods as _a, SETTING_GROUPS as _i, MachineOwner as _n, configCorruptRepair as _o, readIdleStop as _r, ENDED_AGENT_RETENTION_MS as _t, hostedMacosLogsDir as a, deviceViewersDir as aa, SETTINGS_SCHEMA_FILE as ai, DeviceActivity as an, EasSessionClaim as ao, READY_PHASE_MS as ar, offloadSummary as at, HostedDeviceOfferRequest as b, supervisorPidFile as ba, SettingEntry as bi, MemorySource as bn, getConcurrencyLimits as bo, readWorkspaceAgent as br, agentSessionOf as bt, Endpoint as c, easSessionLedgerFile as ca, ANDROID_COMPILER_CACHE_CHOICES as ci, DiskMeasure as cn, readEasSessionLedger as co, WarmRecord as cr, readStatsReport as ct, findPeer as d, getConfigPath as da, IOS_SIMULATOR_APPS as di, EnvironmentState as dn, readJsonFile as do, lastUseFrom as dr, wholePhases as dt, createdDevicesFile as ea, parseHostedAppManifest as ei, BuildPlacement as en, parseNdjsonLine as eo, DeviceIdleShutdownRecord as er, StatsRecord as et, parseMachine as f, gitMergeCacheDir as fa, OFFLOAD_MODES as fi, GitChip as fn, readJsonObject as fo, parseMissReason as fr, DeviceViewersRecord as ft, HostedAndroidChoice as g, sharedGradle as ga, SETTINGS as gi, MEMORY_SOURCES as gn, buildWorkerRoot as go, readDeviceIdleShutdowns as gr, AgentSessionsCache as gt, readDeviceHostMachines as h, sharedCompilationCache as ha, RemoteDeviceBackend as hi, MACHINE_OWNER_KINDS as hn, allMetroPorts as ho, readDevServerStopRequest as hr, stimBuildDigest as ht, HostedLogsPage as i, deviceHostMachinesLock as ia, validHostedAppArguments as ii, ChecksState as in, CreatedDevices as io, MetroLastStop as ir, findProjectRoot as it, deviceHostRoot as j, workspaceStateLock as ja, isLayeredSetting as ji, SimulatorState as jn, DoctorRunRecord as jo, HOSTED_AGENT_DRIVERS as jr, withGitChip as jt, assertHostedDeviceLedger as k, workspaceRecordingsDir as ka, coerceSettingText as ki, RunOutcomeKind as kn, Config as ko, readHostedMacosApp as kr, readPullRequestCache as kt, TailnetPeer as l, easSessionLedgerLock as la, ANDROID_EMULATOR_APPS as li, EndedAgentSession as ln, validEasSessionClaim as lo, WorkspaceState as lr, statsProjectKey as lt, DeviceHostMachineCredential as m, sharedCcache as ma, REMOTE_DEVICE_BACKENDS as mi, LastBuildReport as mn, withStateReadCache as mo, readDevServerStop as mr, readViewedDevices as mt, HOSTED_LOGS_PAGE_BYTES as n, deviceHostMachinesClaims as na, readHostedApp as ni, BuildReport as nn, readNdjsonGenerations as no, IdleStopRecord as nr, StatsScope as nt, parseHostedLogsCursor as o, diskUsageCacheDir as oa, SETTINGS_SCHEMA_URL as oi, DeviceAppProcess as on, EasSessionLedgerRead as oo, WARM_KEY as or, readRunEstimates as ot, pinnedEndpoint as p, pullRequestCacheDir as pa, OffloadMode as pi, GitChipPart as pn, readStateFile as po, readBuildHistory as pr, ViewedDevice as pt, ReadStatsResult as q, sortByTs as qa, recordedBytes as qi, WorktreePullRequest as qn, HOSTED_APP_CHUNK_BYTES as qr, BuildDetail as qt, HostedLogsCursor as r, deviceHostMachinesFile as ra, readHostedAppMetadata as ri, BuildResult as rn, CreatedDevicePlatform as ro, LAST_BUILD_KEYS as rr, decodeStats as rt, readLogsSince as s, easMachineStateRoot as sa, settingsJsonSchema as si, DeviceLeaseState as sn, readCreatedDevices as so, WORKSPACE_AGENT_KEY as sr, readStats as st, HOSTED_LOGS_FIRST_BYTES as t, createdDevicesLock as ta, parseHostedAppOffer as ti, BuildPlanPayload as tn, parseNdjsonText as to, IDLE_STOP_KEY as tr, StatsReport as tt, endpoint as u, emulatorLogFile as ua, ANDROID_PCH_CHOICES as ui, EnvironmentDisk as un, isJsonObject as uo, buildDiagnostics as ur, trimSamples as ut, HostedDevice as v, statsFile as va, SETTING_SCOPES as vi, MachineOwnerKind as vn, findEnclosingWorktreeRoot as vo, readLastBuilds as vr, PullRequestCacheEntry as vt, HostedDeviceSelectors as w, workspaceEndedAgentsLock as wa, TUNNEL_MODES as wi, PHYSICAL_DEVICE_CONNECTIONS as wn, getRepoSettings as wo, MacosAppState as wr, pullRequestCacheFile as wt, HostedDevicePhase as x, workspaceBuildDetailFile as xa, SettingScope as xi, MetroBundleState as xn, getProject as xo, readWorkspaceState as xr, diskUsageCacheFile as xt, HostedDeviceOffer as y, supervisorLogFile as ya, SettingDefinition as yi, MachineUsageState as yn, findProjectByMetroPort as yo, readWarmRecord as yr, StatusCacheEntry as yt, parseHostedPlatformDevice as z, fileSizes as za, RecordedSegment as zi, WORKSPACE_STAGE_KINDS as zn, readBuildMachines as zo, HostedMacosDevice as zr, AgentTool as zt };