stim 1.20.2 → 1.21.0

package/dist/api.d.mts

@@ -1,9 +1,16 @@
-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 { a as DoctorPlatform, c as AndroidFacts, d as IosFacts, i as TailnetMachineIo, l as CcacheActivity, n as BuildMachinesInspection, o as Finding, r as GeneratedTickets, u as CompilationCacheActivity } from "./client-B7QVOlCr.mjs";
+import { i as WorkspaceLaunchPlatform } from "./settings-DkdmlelE.mjs";
+import "./exec-H20xSg2T.mjs";
+import { t as IdleDevice } from "./idle-BVeRGroT.mjs";
+import { readFileSync, writeFileSync } from "node:fs";
+import { StimContext, hostSimulatorArch } from "@stim-cli/core";
+import { ANDROID_EMULATOR_APPS, AgentDeviceUsage, ArchivedWorkspace, MacosBuild, MaintenanceAction, MaintenanceMode, MaintenancePressure, MaintenanceStatus, NdjsonRecord, SettingScope, SettingWriteResult, SettingsPayload, SimRuntimeUsage, StatsReport, SwiftpmCacheUsage, WebBrowserState, WebViewport, machineCapacity } from "@stim-cli/core/state";
 import { Command } from "commander";
+import "@expo/fingerprint";
+import { loadCacheProvider } from "@stim-cli/cache";
+import { ToolchainEntry } from "@stim-cli/core/toolchain";
 import { ChildProcess } from "node:child_process";
+import { HelloResult } from "@stim-cli/core/protocol";
 //#region src/commands/android/build.d.ts
 interface AndroidBuildOptions {
   variant?: string;
@@ -27,6 +34,9 @@ interface AndroidBuildFacts {
   logs: {
     dir: string;
   };
+  links: {
+    workspace: string;
+  };
 }
 //#endregion
 //#region src/commands/macos-build.d.ts
@@ -43,6 +53,9 @@ interface MacosBuildFacts {
   logs: {
     dir: string;
   };
+  links: {
+    workspace: string;
+  };
 }
 //#endregion
 //#region src/commands/ios/build.d.ts
@@ -71,6 +84,9 @@ interface IosBuildFacts {
   logs: {
     dir: string;
   };
+  links: {
+    workspace: string;
+  };
 }
 //#endregion
 //#region src/engine/device-lease.d.ts
@@ -164,6 +180,652 @@ interface WebFacts extends WebBrowserState {
   durationMs: number;
 }
 //#endregion
+//#region src/maintenance/status.d.ts
+declare function maintenanceStatus(env?: NodeJS.ProcessEnv): MaintenanceStatus;
+//#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/budget.d.ts
+type ReclaimStepName = "idle-devices" | "idle-dev-servers" | "workspace-outputs" | "stale-cache-entries";
+interface ReclaimedStep {
+  step: ReclaimStepName;
+  targets: string[];
+  failures: number;
+  freedMb?: number;
+}
+interface BudgetReport {
+  budget: {
+    minFreeDiskGb: number;
+    hardFloorDiskGb: number;
+    maxCommittedMemoryGb: number;
+    maxLiveWorkspaces: number;
+  };
+  volumes: {
+    volume: string;
+    freeGb: number;
+  }[];
+  memory: {
+    committedGb: number;
+    liveWorkspaces: number;
+  } | null;
+  plan: ReclaimedStep[];
+}
+//#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/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/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 +835,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;
   /**
@@ -257,6 +921,13 @@ interface StimStopOptions {
   signal?: AbortSignal;
 }
 type StimStopResult = StopResult;
+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 +938,45 @@ 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;
+}
+interface StimDoctorOptions extends StimReadOptions {
+  platform?: "ios" | "android";
+  /** Records completed iOS/Android checks in project state. Defaults to false for report-only reads. */
+  record?: boolean;
+}
+type StimDoctorReport = DoctorReport;
+type StimGcOptions = GcReadOptions & StimReadOptions;
+type StimGcReport = Exclude<GcPayload, {
+  code: string;
+}>;
+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;
+  /** 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>;
+  /** 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>;
   /** Builds an artifact without acquiring a device or starting a runtime. */
   build<P extends StimBuildOptions["platform"]>(options: StimBuildOptions & {
     platform: P;
@@ -284,8 +992,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;
@@ -305,8 +1034,11 @@ declare class StimError extends Error {
 }
 /**
  * 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 StimGcOptions, type StimGcReport, type StimLogsOptions, type StimOptions, type StimPlatform, type StimProgress, type StimReadOptions, type StimReloadOptions, type StimReloadResult, type StimRunOptions, type StimRunResult, type StimSettingWriteOptions, type StimSettingWriteResult, type StimSettings, type StimStats, type StimStopOptions, type StimStopResult, createStim };