stim 1.20.2 → 1.22.0

package/dist/api.d.mts

@@ -1,16 +1,51 @@
-import { i as IosFacts, n as CcacheActivity, r as CompilationCacheActivity, t as AndroidFacts } from "./build-facts-DcLv2HSd.mjs";
-import "./settings-vk3mJGSm.mjs";
-import "./ndjson-Du3j0AQ9.mjs";
-import { MacosBuild, NdjsonRecord, WebBrowserState, WebViewport } from "@stim-cli/core/state";
+import { _ as IosFacts, a as BuildMachinesInspection, d as DoctorPlatform, f as Finding, g as CompilationCacheActivity, h as CcacheActivity, m as AndroidFacts, n as WebLaunched, o as GeneratedTickets, s as TailnetMachineIo, u as BudgetReport } from "./android-project-DVWyCbWU.mjs";
+import { a as WorkspaceLaunchPlatform } from "./ios-CDvlmUs7.mjs";
+import "./exec-DnYc4HGH.mjs";
+import "./pull-request-eODyIqZF.mjs";
+import { t as IdleDevice } from "./idle-C4cZ757K.mjs";
+import { StimContext } from "@stim-cli/core";
+import { AgentDeviceUsage, ArchivedWorkspace, BuildPlanPayload, MacosBuild, MacosBuildPlanPayload, MaintenanceAction, MaintenanceMode, MaintenancePressure, MaintenanceStatus, NdjsonRecord, SettingScope, SettingWriteResult, SettingsPayload, SimRuntimeUsage, StatsReport, SwiftpmCacheUsage, WebBrowserState } from "@stim-cli/core/state";
+import { statSync } from "fs";
 import { Command } from "commander";
-import { ChildProcess } from "node:child_process";
-//#region src/commands/android/build.d.ts
-interface AndroidBuildOptions {
-  variant?: string;
-  abi?: "arm64-v8a" | "armeabi-v7a" | "x86" | "x86_64" | "all";
-  buildCache?: boolean;
-  remoteBuild?: string;
+import { ToolchainEntry } from "@stim-cli/core/toolchain";
+import { HelloResult, PlatformBuildOptions, PlatformRunOptions } from "@stim-cli/core/protocol";
+//#region src/engine/device-lease.d.ts
+type LeasePlatform = "ios" | "android";
+interface ReleasedLease {
+  platform: LeasePlatform;
+  id: string;
+  deviceName: string | null;
+  expiresAt: string;
+}
+//#endregion
+//#region src/commands/gc/results.d.ts
+type GcResultKind = "archive" | "device" | "parkedDevice" | "parkedHostedDevice" | "idleDevice" | "deviceRecord" | "workspaceOutputs" | "recording" | "workspaceDirectory" | "project" | "buildLock" | "buildSlot" | "deviceLease" | "easSession" | "worktree" | "cache" | "statusCache" | "tempLeftover" | "watchmanRoot" | "watchman" | "gradleDaemon" | "gradleVersion" | "kotlinDaemon";
+type GcResultStatus = "done" | "kept" | "failed";
+interface GcResult {
+  kind: GcResultKind;
+  status: GcResultStatus;
+  label: string;
+  id: string | null;
+  bytes: number | null;
+  detail: string | null;
 }
+//#endregion
+//#region src/supervisor/start-facts.d.ts
+interface StartFacts {
+  port: number;
+  supervisorPid: number | null;
+  mode: string | null;
+  logsDir: string;
+  agentDevice?: {
+    stateDir: string;
+  };
+  alreadyRunning: boolean;
+}
+//#endregion
+//#region src/commands/android/build.d.ts
+type AndroidBuildOptions = Omit<Extract<PlatformBuildOptions, {
+  platform: "android";
+}>, "platform">;
 interface AndroidBuildFacts {
   /** Owned copy, retained with this workspace until explicitly removed. */
   apkPath: string;
@@ -27,12 +62,15 @@ interface AndroidBuildFacts {
   logs: {
     dir: string;
   };
+  links: {
+    workspace: string;
+  };
 }
 //#endregion
 //#region src/commands/macos-build.d.ts
-interface MacosBuildOptions {
-  remoteBuild?: string;
-}
+type MacosBuildOptions = Omit<Extract<PlatformBuildOptions, {
+  platform: "macos";
+}>, "platform">;
 interface MacosBuildFacts {
   product: string;
   /** Owned copy, retained with this workspace until explicitly removed. */
@@ -43,17 +81,15 @@ interface MacosBuildFacts {
   logs: {
     dir: string;
   };
+  links: {
+    workspace: string;
+  };
 }
 //#endregion
 //#region src/commands/ios/build.d.ts
-interface IosBuildOptions {
-  configuration?: string;
-  scheme?: string;
-  /** Simulator architecture. Defaults to the host for Debug, or all architectures otherwise. */
-  arch?: "arm64" | "x86_64" | "all";
-  buildCache?: boolean;
-  remoteBuild?: string;
-}
+type IosBuildOptions = Omit<Extract<PlatformBuildOptions, {
+  platform: "ios";
+}>, "platform">;
 interface IosBuildFacts {
   /** Owned simulator app, retained with this workspace until explicitly removed. */
   appPath: string;
@@ -71,15 +107,9 @@ interface IosBuildFacts {
   logs: {
     dir: string;
   };
-}
-//#endregion
-//#region src/engine/device-lease.d.ts
-type LeasePlatform = "ios" | "android";
-interface ReleasedLease {
-  platform: LeasePlatform;
-  id: string;
-  deviceName: string | null;
-  expiresAt: string;
+  links: {
+    workspace: string;
+  };
 }
 //#endregion
 //#region src/commands/stop.d.ts
@@ -149,9 +179,6 @@ interface TunnelOutcome {
   reason?: string;
 }
 //#endregion
-//#region src/web/launch.d.ts
-type WebLaunched = true | "bundling" | "unverified";
-//#endregion
 //#region src/commands/web.d.ts
 interface WebFacts extends WebBrowserState {
   platform: "web";
@@ -164,6 +191,614 @@ interface WebFacts extends WebBrowserState {
   durationMs: number;
 }
 //#endregion
+//#region src/maintenance/status.d.ts
+declare function maintenanceStatus(env?: NodeJS.ProcessEnv): MaintenanceStatus;
+//#endregion
+//#region src/diagnostics/stim-installations.d.ts
+interface StimInstallation {
+  path: string;
+  realPath: string;
+  version: string | null;
+}
+interface StimVersionReport {
+  runningVersion: string;
+  runningPath: string | null;
+  resolved: StimInstallation | null;
+  installations: StimInstallation[];
+  versions: string[];
+  highestVersion: string | null;
+  resolvedIsOlder: boolean;
+}
+//#endregion
+//#region src/device-host/machines.d.ts
+interface MachineReport {
+  machine: string;
+  state: "invalid" | "tailscale-off" | "not-on-tailnet" | "key-changed" | "not-asked" | "pending" | "approved" | "revoked" | "lapsed" | "outdated" | "unreachable" | "credentials-unavailable" | "busy";
+  dnsName?: string;
+  deviceId?: string;
+  requestedAt?: string;
+  expiresAt?: string;
+  host?: NonNullable<HelloResult["host"]>;
+}
+interface Inspection {
+  findings: Finding[];
+  machines: MachineReport[];
+}
+/**
+ * Reports the device-host approval of each remote machine, separate from its build approval. Only --fix makes a setup
+ * ticket or forgets credentials; every server key stays pinned.
+ */
+declare function inspectDeviceHostMachines({ fix, version, tickets, operation }: {
+  fix: boolean;
+  version?: string;
+  tickets?: GeneratedTickets;
+  operation?: StimContext;
+}, io?: TailnetMachineIo, entries?: string[] | null): Promise<Inspection>;
+//#endregion
+//#region src/commands/doctor.d.ts
+/**
+ * Where the toolchain a process without a login shell, such as stim-server under Stim Desktop, finds each tool,
+ * and the Node the project's dev server runs on.
+ */
+interface ToolchainReport {
+  entries: ToolchainEntry[];
+  projectNode: {
+    pin: string;
+    spec: string;
+    bin: string | null;
+    version: string | null;
+  } | null;
+}
+interface DoctorReport {
+  project: string;
+  platform: DoctorPlatform | null;
+  stim: StimVersionReport;
+  budget: BudgetReport | null;
+  maintenance: ReturnType<typeof maintenanceStatus> & {
+    logPath: string;
+  };
+  remoteMachines: BuildMachinesInspection["machines"];
+  deviceHosts: Awaited<ReturnType<typeof inspectDeviceHostMachines>>["machines"];
+  toolchain: ToolchainReport | null;
+  findings: Finding[];
+}
+//#endregion
+//#region src/commands/gc/worktrees.d.ts
+type WorktreeSkipCode = "not-a-worktree" | "bare-repository" | "source-checkout-unknown" | "source-checkout" | "locked" | "nested-worktree" | "in-use" | "status-unreadable" | "dirty" | "unpushed-unchecked" | "unpushed" | "submodules" | "not-merged" | "merge-unknown" | "last-use-unknown" | "recently-used" | "activity-unknown" | "recent-activity";
+interface WorktreeBuildState {
+  bytes: number | null;
+  dirs: {
+    path: string;
+    bytes: number | null;
+  }[];
+}
+//#endregion
+//#region src/maintenance/plan.d.ts
+interface MaintenancePlan {
+  actions: MaintenanceAction[];
+  blocked: string[];
+  skips: {
+    target: string;
+    reason: string;
+    workspace?: string;
+  }[];
+}
+//#endregion
+//#region src/maintenance/preview.d.ts
+interface MaintenancePreview extends MaintenancePlan {
+  mode: MaintenanceMode;
+  invalid?: string;
+  pressure: MaintenancePressure | null;
+  note: string | null;
+}
+//#endregion
+//#region src/commands/gc/devices.d.ts
+interface ParkedSimReport {
+  udid: string;
+  name: string;
+  model: string | null;
+  runtime: string | null;
+  parkedAt: string;
+  app: string | null;
+  bytes: number | null;
+  listed: boolean | null;
+}
+interface ParkedAvdReport {
+  name: string;
+  systemImage: string;
+  deviceProfile: string | null;
+  parkedAt: string;
+  app: string | null;
+  bytes: number | null;
+  listed: boolean | null;
+}
+//#endregion
+//#region src/commands/gc/hosted-devices.d.ts
+interface ParkedHostedDeviceReport {
+  session: string;
+  client: string;
+  platform: "ios" | "android";
+  id: string | null;
+  name: string | null;
+  parkedAt: string;
+  listed: boolean | null;
+}
+//#endregion
+//#region src/archive.d.ts
+interface ArchiveStaging {
+  path: string;
+  kept: boolean;
+  reason: string | null;
+  removeCommand: string | null;
+}
+//#endregion
+//#region src/commands/gc/archive-selector.d.ts
+type ArchiveKind = "logs" | "recordings" | "agentActions";
+//#endregion
+//#region src/commands/gc/archives.d.ts
+interface ArchiveSelection {
+  records: {
+    id: string;
+    kinds: string[];
+    bytes: number;
+    expires: ArchivedWorkspace["expires"];
+    willDelete: boolean;
+  }[];
+  staging: ArchiveStaging[];
+  unknownId: string | null;
+  knownIds: string[];
+  kind: ArchiveKind | null;
+}
+//#endregion
+//#region src/devices/machine-cache-usage.d.ts
+interface SizedDir {
+  dir: string;
+  bytes: number | null;
+}
+interface MachineCacheReport {
+  measuredAt: string;
+  complete: boolean;
+  notices: string[];
+  gradle: {
+    home: string;
+    unusedVersions: {
+      version: string;
+      bytes: number | null;
+      dirs: SizedDir[];
+      remedy: string | null;
+    }[];
+    usedVersions: {
+      version: string;
+      projects: string[];
+    }[];
+    unreadableProjects: string[];
+    modules: (SizedDir & {
+      remedy: string;
+    }) | null;
+  };
+  simRuntimes: {
+    checked: boolean;
+    runtimes: (SimRuntimeUsage & {
+      remedy: string | null;
+    })[];
+  };
+  deviceSupport: {
+    entries: SizedDir[];
+    remedy: string;
+  };
+  runnerBuilds: {
+    agentDeviceVersion: string | null;
+    xcodeBuildVersion: string | null;
+    groups: {
+      packageVersion: string | null;
+      xcodeBuildVersion: string | null;
+      current: boolean | null;
+      entries: number;
+      inUse: number;
+      bytes: number | null;
+      oldestUseAt: string | null;
+    }[];
+    remedy: string;
+  };
+}
+//#endregion
+//#region src/commands/gc/gradle-versions.d.ts
+type GradleSweepBlock = "machine-global" | "no-registry" | "unsafe-layout" | "listing-failed" | "unreadable-project" | "gradle-running" | "processes-unknown";
+type GradleVersionKeptCode = GradleSweepBlock | "pinned" | "not-a-directory" | "walk-failed" | "too-many-entries" | "recently-modified";
+interface GradleVersionEntry {
+  version: string;
+  dirs: string[];
+  bytes: number | null;
+  lastModifiedAt: string | null;
+  willDelete: boolean;
+  reason: GradleVersionKeptCode | null;
+  detail: string | null;
+}
+interface GradleVersionSweep {
+  home: string;
+  olderThanDays: number | null;
+  blocked: {
+    reason: GradleSweepBlock;
+    detail: string;
+  } | null;
+  /** Why running Gradle blocks deletion; with `pastRunningGradle`, versions are judged as if it had stopped. */
+  gradleRunning: string | null;
+  /** The pids of the Gradle processes behind `gradleRunning`. */
+  gradleRunningPids: number[];
+  versions: GradleVersionEntry[];
+  leftovers: string[];
+}
+//#endregion
+//#region src/commands/gc/workspaces.d.ts
+type WorkspaceKeptCode = "unresolved" | "in-use" | "last-use-unknown" | "recently-used";
+//#endregion
+//#region src/commands/gc/logs.d.ts
+type WorkspaceLogsKeptCode = "unresolved" | "in-use" | "collector";
+//#endregion
+//#region src/commands/gc/finished-devices.d.ts
+interface OwnedDeviceDisk {
+  kind: "ios" | "android";
+  count: number;
+  bytes: number;
+  /** Owned devices whose disk could not be measured; `bytes` leaves them out. */
+  unmeasured: number;
+}
+//#endregion
+//#region src/commands/gc/recordings.d.ts
+type RecordingKeptCode = "unresolved" | "retained" | "recently-recorded";
+//#endregion
+//#region src/commands/gc/temp-leftovers.d.ts
+type TempLeftoverKind = "stim" | "xctrace" | "jest";
+interface TempLeftover {
+  kind: TempLeftoverKind;
+  path: string;
+  bytes: number;
+  willDelete: boolean;
+  kept: string | null;
+}
+interface TempLeftoverReport {
+  root: string;
+  entries: TempLeftover[];
+  /** Judges an entry again right before deletion (a Stim directory after its rename to `staged`), so a claim or recording use since the scan keeps it. */
+  recheck?: (staged: string, original: string, kind: "stim" | "xctrace") => Promise<string | null>;
+}
+interface TempLeftoverGroup {
+  kind: TempLeftoverKind;
+  count: number;
+  bytes: number;
+  deleteCount: number;
+  deleteBytes: number;
+  kept: {
+    reason: string;
+    count: number;
+  }[];
+  remedy: string;
+}
+declare function tempLeftoverSection(report: TempLeftoverReport | null | undefined): {
+  root: string;
+  groups: TempLeftoverGroup[];
+} | null;
+//#endregion
+//#region src/commands/gc/memory.d.ts
+declare const WATCHMAN_KIND = "watchman";
+declare const GRADLE_DAEMONS_KIND = "gradle-daemons";
+type MemoryCacheKind = typeof WATCHMAN_KIND | typeof GRADLE_DAEMONS_KIND;
+type MemoryKeptCode = "in-use" | "busy" | "unknown" | "build-running" | "stim-server";
+interface MemoryProcess {
+  kind: "watchman" | "gradleDaemon" | "kotlinDaemon";
+  cacheKind: MemoryCacheKind;
+  pid: number;
+  startedAt: string | null;
+  bytes: number;
+  measure: "footprint" | "rss";
+  version: string | null;
+  gradleHome: string | null;
+  offloadClient: string | null;
+  state: "idle" | "busy" | "unknown";
+  reclaimable: boolean;
+  reason: MemoryKeptCode | null;
+  detail: string | null;
+}
+type WatchmanRootStale = "missing" | "pruned-worktree";
+interface WatchmanRoot {
+  path: string;
+  stale: WatchmanRootStale | null;
+  subscriptions: number | null;
+  triggers: number | null;
+  removable: boolean;
+  detail: string | null;
+}
+//#endregion
+//#region src/commands/gc/report.d.ts
+interface GcJsonLock {
+  path: string;
+  platform: string;
+  key: string | null;
+  pid: number | null;
+  projectRoot: string | null;
+}
+/** The `gc --json` sections, in text report order. Sections contain entries or a report-only usage payload. */
+interface GcJsonSections {
+  archived?: ArchiveSelection["records"];
+  archiveStaging?: ArchiveSelection["staging"];
+  deadProjects: {
+    path: string;
+  }[];
+  invalidProjects: {
+    path: string;
+  }[];
+  orphanedPorts: {
+    project: string;
+    label: string;
+    port: number;
+  }[];
+  orphanedWorkspaces: {
+    dir: string;
+    projectRoot: string;
+    bytes: number | null;
+  }[];
+  linkedWorktrees: {
+    path: string;
+    idleDays: number | null;
+    mergedInto: string | null;
+    pullRequest: {
+      number: number;
+      state: "open" | "merged" | "closed";
+      url: string;
+      containsHead: boolean;
+    } | null;
+    pullRequestUnknown: string | null;
+    willRemove: boolean;
+    reason: WorktreeSkipCode | null;
+    detail: string;
+    eligibleAt: string | null;
+    buildState: WorktreeBuildState | null;
+  }[];
+  unlistedWorktreeDirectories: {
+    path: string;
+    repository: string;
+    bytes: number | null;
+    remedy: string;
+  }[];
+  parkedSimulators: ParkedSimReport[];
+  parkedEmulators: ParkedAvdReport[];
+  parkedHostedDevices: ParkedHostedDeviceReport[];
+  orphanedDevices: {
+    kind: "ios" | "android";
+    id: string;
+    name: string;
+    bytes: number | null;
+    directory: string | null;
+  }[];
+  unverifiedDevices: {
+    kind: "ios" | "android";
+    id: string;
+    name: string;
+    command: string;
+  }[];
+  staleDevices: {
+    kind: "ios" | "android";
+    id: string;
+    name: string;
+    project: string;
+    slot: string | null;
+    idleDays: number;
+    bytes: number | null;
+  }[];
+  finishedDevices: {
+    kind: "ios" | "android";
+    id: string;
+    name: string;
+    project: string;
+    slot: string | null;
+    bytes: number | null;
+    reason: string;
+  }[];
+  ownedDeviceDisk: OwnedDeviceDisk[];
+  staleDeviceRecords: {
+    kind: "ios" | "android";
+    id: string;
+    project: string;
+    slot: string | null;
+  }[];
+  staleLedgerEntries: {
+    kind: "ios" | "android" | "web";
+    id: string;
+  }[];
+  staleEasLedgerEntries: {
+    id: string;
+    workspaceRoot: string;
+  }[];
+  staleStatusCaches: {
+    kind: "disk-usage" | "pull-request";
+    path: string;
+    file: string;
+    bytes: number;
+  }[];
+  idleDevices: IdleDevice[];
+  orphanedEasSessions: {
+    id: string;
+    name: string;
+    platform: "ios" | "android";
+    status: string;
+    projectScope: string;
+  }[];
+  staleBuildLocks: GcJsonLock[];
+  staleBuildSlots: {
+    path: string;
+    index: number | null;
+    pid: number | null;
+    projectRoot: string | null;
+  }[];
+  unresolvedBuildClaims: {
+    kind: "lock" | "slot";
+    path: string;
+  }[];
+  buildsInProgress: GcJsonLock[];
+  expiredDeviceLeases: {
+    path: string;
+    platform: string;
+    id: string;
+    deviceName: string | null;
+    holder: string | null;
+    expiresAt: string | null;
+  }[];
+  keptDeviceLeases: {
+    name: string;
+    path: string;
+    detail: string;
+  }[];
+  deviceSweepNotices: {
+    message: string;
+  }[];
+  easSessionSweepNotices: {
+    message: string;
+  }[];
+  skipped: {
+    path: string;
+    detail: string;
+  }[];
+  workspaceLogs: {
+    dir: string;
+    projectRoot: string | null;
+    bytes: number;
+    trimBytes: number;
+    willTrim: boolean;
+    reason: WorkspaceLogsKeptCode | null;
+    detail: string | null;
+  }[];
+  recordings: {
+    dir: string;
+    projectRoot: string | null;
+    bytes: number;
+    deleteBytes: number;
+    willDelete: boolean;
+    withWorkspace: boolean;
+    reason: RecordingKeptCode | null;
+    detail: string | null;
+  }[];
+  workspaceBuildOutputs: {
+    dir: string;
+    projectRoot: string | null;
+    bytes: number | null;
+    idleDays: number | null;
+    willClear: boolean;
+    reason: WorkspaceKeptCode | null;
+    detail: string | null;
+  }[];
+  agentDevice: AgentDeviceUsage | null;
+  swiftpmCache: SwiftpmCacheUsage | null;
+  machineCaches: MachineCacheReport | null;
+  tempLeftovers: ReturnType<typeof tempLeftoverSection>;
+  gradleVersions: GradleVersionSweep | null;
+  caches: {
+    name: string;
+    dir: string;
+    source: "registered" | "detected" | null;
+    bytes: number | null;
+    note: string | null;
+    willEmpty: boolean;
+    emptySkipped: string | null;
+    scopedEmpty: {
+      willEmpty: boolean;
+      emptySkipped: string | null;
+    } | null;
+  }[];
+  memory: MemoryProcess[];
+  watchmanRoots: WatchmanRoot[];
+  memoryNotices: {
+    message: string;
+  }[];
+}
+//#endregion
+//#region src/commands/gc/inventory.d.ts
+/**
+ * Who a simulator or AVD belongs to: a workspace of this Stim home, this home's parked pool, this home
+ * with no workspace left, a `stim-*` device this home has no record of creating, or the user.
+ */
+type InventoryOwner = "workspace" | "parked" | "orphaned" | "otherStimHome" | "user";
+interface InventoryDevice {
+  kind: "ios" | "android";
+  id: string;
+  name: string;
+  model: string | null;
+  runtime: string | null;
+  state: string | null;
+  lastUsedAt: string | null;
+  bytes: number | null;
+  directory: string | null;
+  owner: InventoryOwner;
+  project: string | null;
+  slot: string | null;
+}
+interface InventoryRuntime {
+  identifier: string;
+  runtimeIdentifier: string | null;
+  version: string | null;
+  build: string | null;
+  bytes: number | null;
+  lastUsedAt: string | null;
+  deviceCount: number;
+  command: string | null;
+}
+interface InventorySystemImage {
+  package: string;
+  directory: string;
+  avdCount: number;
+  command: string;
+}
+interface GcInventory {
+  devices: InventoryDevice[];
+  runtimes: InventoryRuntime[];
+  systemImages: InventorySystemImage[];
+  notices: string[];
+}
+//#endregion
+//#region src/commands/gc.d.ts
+interface RunGcOptions {
+  idle?: number;
+  olderThan?: number;
+  cache?: string;
+  delete?: boolean;
+  worktrees?: boolean;
+  json?: boolean;
+}
+interface GcRefusal {
+  code: string;
+  message: string;
+  remedy: string;
+}
+type GcPayload = {
+  mode: "dry-run" | "delete";
+  idle: number | null;
+  cacheScope: string | null;
+  olderThan: number | null;
+  worktreeSweep: {
+    olderThan: number;
+    defaulted: boolean;
+  } | null;
+  actionable: boolean;
+  failures: number | null;
+  sections: GcJsonSections;
+  maintenance?: MaintenancePreview;
+  results: GcResult[];
+  inventory: GcInventory | null;
+} | GcRefusal;
+type GcReadOptions = Pick<RunGcOptions, "olderThan" | "cache" | "worktrees">;
+//#endregion
+//#region src/commands/reload.d.ts
+type ReloadPlatform = WorkspaceLaunchPlatform | "web";
+interface ReloadFacts {
+  platform: ReloadPlatform;
+  deviceId: string;
+  deviceName: string;
+  appId: string;
+  metroPort: number | null;
+  strategy: "metro-websocket" | "metro-broadcast" | "cdp";
+  targets: number | null;
+  reverseRestored: string[];
+}
+//#endregion
 //#region src/api/types.d.ts
 type StimPlatform = "ios" | "android" | "macos" | "web";
 interface StimProgress {
@@ -173,8 +808,10 @@ interface StimProgress {
 interface StimOptions {
   /** Absolute or relative path to the app directory, resolved once when creating the client. */
   projectRoot: string;
-  /** Absolute Stim state directory. Omit to use the caller's STIM_HOME or the default home. */
+  /** Absolute Stim state directory. Omit to use STIM_HOME from `env` or the default home. */
   home?: string;
+  /** Environment Stim reads its settings overrides from and passes to its child processes. Defaults to the caller's `process.env`. */
+  env?: NodeJS.ProcessEnv;
   /** Absolute native artifact cache directory. Its coordinating home must be shared by all writers. */
   buildCache?: string;
   /**
@@ -183,30 +820,7 @@ interface StimOptions {
    */
   onProgress?: (event: StimProgress) => void;
 }
-interface NativeRunOptions {
-  slot?: string;
-  metroCheck?: boolean;
-  buildCache?: boolean;
-  remoteBuild?: string;
-}
-type StimRunOptions = ((NativeRunOptions & {
-  platform: "ios";
-  configuration?: string;
-  scheme?: string;
-  deviceType?: string;
-  runtime?: string;
-}) | (NativeRunOptions & {
-  platform: "android";
-  variant?: string;
-  systemImage?: string;
-  deviceProfile?: string;
-}) | {
-  platform: "macos";
-  remoteBuild?: string;
-} | {
-  platform: "web";
-  headed?: boolean;
-}) & {
+type StimRunOptions = PlatformRunOptions & {
   signal?: AbortSignal;
 };
 type StimRunResult = {
@@ -223,7 +837,7 @@ type StimRunResult = {
     bundleId: string;
     executable: string;
     pid: number | null;
-    launched: boolean;
+    launched: boolean | "unverified";
     build: MacosBuild;
     logs: {
       dir: string;
@@ -255,8 +869,26 @@ type StimBuildResult = {
 interface StimStopOptions {
   slot?: string;
   signal?: AbortSignal;
+  /** Runs once with the resolved workspace before teardown; throwing refuses the operation. */
+  beforeStop?: (workspace: string) => void;
 }
 type StimStopResult = StopResult;
+interface StimStartOptions {
+  remote?: boolean;
+  resetCache?: boolean;
+  waitSeconds?: number;
+  signal?: AbortSignal;
+  /** Runs once with the resolved app before usage recording or startup; throwing refuses the operation. */
+  beforeStart?: (workspace: string) => void;
+}
+type StimStartResult = StartFacts;
+interface StimReloadOptions {
+  platform?: ReloadPlatform;
+  signal?: AbortSignal;
+  /** Runs once with the resolved workspace before usage recording or a reload; throwing refuses the operation. */
+  beforeReload?: (workspace: string) => void;
+}
+type StimReloadResult = ReloadFacts;
 interface StimDiagnosticsOptions {
   /** Maximum number of records, default 200. Zero returns paths without records. */
   tail?: number;
@@ -267,8 +899,98 @@ interface StimDiagnostics {
   directory: string;
   records: NdjsonRecord[];
 }
+interface StimLogsOptions {
+  slot?: string;
+  sources?: string[];
+  minLevel?: string;
+  since?: string;
+  grep?: string;
+  tail?: number;
+  errorsOnly?: boolean;
+  signal?: AbortSignal;
+}
+interface StimReadOptions {
+  signal?: AbortSignal;
+}
+type StimPlanOptions = ({
+  platform: "ios" | "android";
+  slot?: string;
+} | {
+  platform: "macos";
+}) & StimReadOptions;
+type StimPlan = BuildPlanPayload | MacosBuildPlanPayload;
+interface StimDoctorOptions extends StimReadOptions {
+  platform?: "ios" | "android";
+  /** Records completed iOS/Android checks in project state. Defaults to false for report-only reads. */
+  record?: boolean;
+}
+interface StimMachineAccessOptions extends StimReadOptions {
+  /** The setup ticket generated by the caller. Omit to reuse or generate tickets for the configured machines. */
+  ticket?: string;
+}
+type StimDoctorReport = DoctorReport;
+type StimGcOptions = GcReadOptions & StimReadOptions;
+type StimGcReport = Exclude<GcPayload, {
+  code: string;
+}>;
+type StimGcMutationOptions = StimGcOptions & {
+  delete?: boolean;
+  /** Shuts down owned devices idle for at least this many milliseconds, including without `delete`. */
+  idleMs?: number;
+};
+interface StimGcMutationResult {
+  report: StimGcReport;
+  exitCode: 0 | 1;
+}
+interface StimWorktreeWarmOptions extends StimReadOptions {
+  /** Called for each canonical workspace in the resolved warming scope before effects; throwing refuses warming. */
+  beforeWarm?: (workspace: string) => void;
+}
+interface StimWorktreeWarmResult {
+  exitCode: 0 | 1;
+}
+interface StimWorktreeRemoveOptions extends StimReadOptions {
+  /** Called for each canonical workspace in the resolved cleanup scope before effects; throwing refuses cleanup. */
+  beforeRemove?: (workspace: string) => void;
+  /** Defaults to the client's projectRoot. Relative paths resolve against that directory. */
+  target?: string;
+  /** Allows removal with uncommitted or unpushed work or initialized submodules, as CLI --force does. */
+  force?: boolean;
+}
+interface StimWorktreeRemoveResult {
+  /** True once the linked Git worktree is removed, even if later branch cleanup fails. */
+  removed: boolean;
+  /** Source checkout environment cleanup can succeed without removing the checkout. */
+  exitCode: 0 | 1;
+}
+type StimSettings = SettingsPayload;
+type StimSettingWriteResult = SettingWriteResult;
+interface StimSettingWriteOptions extends StimReadOptions {
+  scope?: SettingScope;
+  /** Runs once with the resolved workspace before mutation; throwing refuses the write. */
+  beforeWrite?: (workspace: string | null) => void;
+}
+type StimStats = StatsReport;
 interface StimClient {
   readonly projectRoot: string;
+  /** Starts or reuses the app's dev server; resources remain workspace-owned until stop is called. */
+  start(options?: StimStartOptions): Promise<StimStartResult>;
+  /** Returns this home's persistent nonsecret identity, initializing it under the config lock on first use. */
+  identity(options?: StimReadOptions): Promise<string>;
+  /** Reads findings with a 60 second execution and 35 second cleanup budget. Never repairs; records a completed check only with `record: true`. */
+  doctor(options?: StimDoctorOptions): Promise<StimDoctorReport>;
+  /** Requests build/device-host approval with a 120 second execution and 35 second cleanup budget. Never grants access or repairs project state. */
+  requestMachineAccess(options?: StimMachineAccessOptions): Promise<StimDoctorReport>;
+  /** Predicts the configured native build with a 60 second execution and 35 second cleanup budget; never builds or launches. */
+  plan(options: StimPlanOptions): Promise<StimPlan>;
+  /** Reads the GC dry-run report with a 60 second execution and 35 second cleanup budget. Never deletes, repairs or shuts down idle resources. */
+  gc(options?: StimGcOptions): Promise<StimGcReport>;
+  /** Executes requested GC actions, preserving partial results and waiting for owned cleanup before releasing maintenance admission. */
+  collectGarbage(options?: StimGcMutationOptions): Promise<StimGcMutationResult>;
+  /** Copies missing ignored state from the source checkout into this linked worktree. */
+  warmWorktree(options?: StimWorktreeWarmOptions): Promise<StimWorktreeWarmResult>;
+  /** Removes a linked worktree or reclaims a source checkout's environment using the CLI safety checks. */
+  removeWorktree(options?: StimWorktreeRemoveOptions): Promise<StimWorktreeRemoveResult>;
   /** Builds an artifact without acquiring a device or starting a runtime. */
   build<P extends StimBuildOptions["platform"]>(options: StimBuildOptions & {
     platform: P;
@@ -284,8 +1006,29 @@ interface StimClient {
   run(options: StimRunOptions): Promise<StimRunResult>;
   /** Stops this workspace, including resources created before a failed run. Use a fresh signal for cleanup. */
   stop(options?: StimStopOptions): Promise<StimStopResult>;
-  /** Reads the existing local timeline; available even when run failed before creating any logs. */
+  /** Requests a JavaScript or owned Chrome reload. Completion is not observed; cancellation cannot undo a sent request. */
+  reload(options?: StimReloadOptions): Promise<StimReloadResult>;
+  /** Reads the existing local timeline in process; available even when run failed before creating any logs. */
   diagnostics(options?: StimDiagnosticsOptions): Promise<StimDiagnostics>;
+  /**
+   * Every setting with its effective value, origin and per-layer values for this project, as `stim settings --json`
+   * prints them. Runs in the calling process without blocking its event loop on child processes.
+   */
+  settings(options?: StimReadOptions): Promise<StimSettings>;
+  /** Writes CLI text (including JSON for object/array settings) to one layer; returned sensitive values are masked. */
+  setSetting(key: string, value: string, options?: StimSettingWriteOptions): Promise<StimSettingWriteResult>;
+  /** Removes one layer value. Cancellation prevents a pending write; committed writes finish recording cleanup. */
+  unsetSetting(key: string, options?: StimSettingWriteOptions): Promise<StimSettingWriteResult>;
+  /**
+   * Run and build-cache counts for this project and machine, build placement and the last recorded agent-device and
+   * SwiftPM cache usage, as `stim stats --json` prints them except that the usage figures are not measured again.
+   * Runs in the calling process without blocking its event loop on child processes.
+   */
+  stats(options?: StimReadOptions): Promise<StimStats>;
+  /** Reads the merged raw log timeline, including native crashes and agent actions, as `stim logs --json`. */
+  logs(options?: StimLogsOptions): Promise<NdjsonRecord[]>;
+  /** Emits backfill, then appended records until stopped or aborted. With onBackfill, initial batches are awaited there instead. */
+  followLogs(options: StimLogsOptions, onRecord: (record: NdjsonRecord) => void, onBackfill?: (records: readonly NdjsonRecord[]) => Promise<void>): Promise<() => void>;
 }
 interface StimFailure {
   code: string;
@@ -301,12 +1044,15 @@ declare class StimError extends Error {
   readonly details: unknown;
   constructor({ code, message, remedy, details }: Omit<StimFailure, "remedy"> & {
     remedy?: string | null;
-  });
+  }, options?: ErrorOptions);
 }
 /**
  * Creates a client without starting processes or changing the caller's cwd, environment, or signal handlers.
- * Each operation runs in a separate Stim worker. Resources remain workspace-owned until stop() is called.
+ * The Stim home is fixed when the client is created: `home`, else STIM_HOME from `env`, else the default home.
+ * Operations run in the calling process against the client's home and project, so clients for different
+ * homes can share a process.
+ * Resources remain workspace-owned until stop() is called.
  */
 declare function createStim(options: StimOptions): StimClient;
 //#endregion
-export { type StimBuildOptions, type StimBuildResult, type StimClient, type StimDiagnostics, type StimDiagnosticsOptions, StimError, type StimOptions, type StimPlatform, type StimProgress, type StimRunOptions, type StimRunResult, type StimStopOptions, type StimStopResult, createStim };
+export { type StimBuildOptions, type StimBuildResult, type StimClient, type StimDiagnostics, type StimDiagnosticsOptions, type StimDoctorOptions, type StimDoctorReport, StimError, type StimGcMutationOptions, type StimGcMutationResult, type StimGcOptions, type StimGcReport, type StimLogsOptions, type StimMachineAccessOptions, type StimOptions, type StimPlan, type StimPlanOptions, type StimPlatform, type StimProgress, type StimReadOptions, type StimReloadOptions, type StimReloadResult, type StimRunOptions, type StimRunResult, type StimSettingWriteOptions, type StimSettingWriteResult, type StimSettings, type StimStartOptions, type StimStartResult, type StimStats, type StimStopOptions, type StimStopResult, type StimWorktreeRemoveOptions, type StimWorktreeRemoveResult, type StimWorktreeWarmOptions, type StimWorktreeWarmResult, createStim };