From ff2b01ec67cf033e5a16cafd9efe03473ed22f80 Mon Sep 17 00:00:00 2001 From: Szymon Chmal Date: Tue, 17 Nov 2026 11:35:12 +0100 Subject: [PATCH 01/15] test: a slim device is slim when only an exclude name is written off (#1650) --- src/drivers/ios/definition.ts | 4 ++ src/drivers/ios/slim-named-services.test.ts | 74 +++++++++++++++++++++ src/drivers/ios/test-slim.ts | 6 +- 3 files changed, 80 insertions(+), 4 deletions(-) create mode 100644 src/drivers/ios/slim-named-services.test.ts diff --git a/src/drivers/ios/definition.ts b/src/drivers/ios/definition.ts index a57914fbc..cdbb35f9d 100644 --- a/src/drivers/ios/definition.ts +++ b/src/drivers/ios/definition.ts @@ -12,6 +12,10 @@ export interface IosDriverConfig { readonly slim: { /** why: undefined disables every category the driver knows. */ readonly categories?: readonly string[]; + /** why: services a slim device keeps running whatever the categories turn off (ADR 0083 §2). */ + readonly include?: readonly string[]; + /** why: services a slim device turns off beside the categories (ADR 0083 §2). */ + readonly exclude?: readonly string[]; /** why: a slim device gets its own boot deadline, because CI runners are slow. */ readonly bootTimeoutMs: number; }; diff --git a/src/drivers/ios/slim-named-services.test.ts b/src/drivers/ios/slim-named-services.test.ts new file mode 100644 index 000000000..34cab2b35 --- /dev/null +++ b/src/drivers/ios/slim-named-services.test.ts @@ -0,0 +1,74 @@ +import { describe, expect, it, vi } from "vitest"; + +import { FakeClock, ScriptedProcessRunner } from "../../ports/index.js"; +import type { IosDriverConfig } from "./definition.js"; +import type { SlimmedFact, SlimSkippedFact } from "./index.js"; +import { + createSlimDriver, + driverData, + FaultyFilesystem, + overridesPath, + parseOverrides, + plantManagedDevice, + printDisabled, + slimBootCalls, +} from "./test-slim.js"; + +const slim18_5 = { ...driverData, runtimeId: "com.apple.CoreSimulator.SimRuntime.iOS-18-5" }; +const diagnosticd = "com.apple.diagnosticd"; + +async function boot(options: { + readonly slim: Omit; + readonly readback: Readonly>; + readonly except?: readonly string[]; +}) { + const filesystem = new FaultyFilesystem(); + await plantManagedDevice(filesystem); + const calls = slimBootCalls(slim18_5.udid, ""); + const runner = new ScriptedProcessRunner([ + ...calls.slice(0, 3), + { + match: calls[3]!.match, + result: { code: 0, stderr: "", stdout: printDisabled(options.readback) }, + }, + ]); + const onSlimmed = vi.fn<(fact: SlimmedFact) => void>(); + const onSlimSkipped = vi.fn<(fact: SlimSkippedFact) => void>(); + const driver = await createSlimDriver( + runner, + filesystem, + { bootTimeoutMs: 300_000, ...options.slim }, + onSlimmed, + onSlimSkipped, + false, + new FakeClock(), + ); + const outcome = await driver + .makeReady( + { address: slim18_5.udid, deviceId: slim18_5.udid, driverData: slim18_5 }, + { except: options.except ?? [], mode: "slim", purpose: "prepare" }, + ) + .then( + (result) => ({ result }) as const, + (error: unknown) => ({ error }) as const, + ); + const file = overridesPath(slim18_5.udid); + const written = (await filesystem.exists(file)) + ? parseOverrides(await filesystem.readFile(file)) + : undefined; + return { onSlimSkipped, onSlimmed, outcome, written }; +} + +describe("IosSimctlDriver makeReady with include and exclude names", () => { + it("grants the mode the readback shows for the named services", async () => { + const excludeOnly = await boot({ + slim: { categories: [], exclude: [diagnosticd] }, + readback: { [diagnosticd]: "disabled" }, + }); + expect(excludeOnly.written?.[diagnosticd]).toBe(true); + expect(excludeOnly.outcome).toEqual({ result: expect.objectContaining({ mode: "slim" }) }); + expect(excludeOnly.onSlimmed).toHaveBeenCalledWith( + expect.objectContaining({ categories: [], labelCount: 1 }), + ); + }); +}); diff --git a/src/drivers/ios/test-slim.ts b/src/drivers/ios/test-slim.ts index 03d03dbfc..9b81717af 100644 --- a/src/drivers/ios/test-slim.ts +++ b/src/drivers/ios/test-slim.ts @@ -11,6 +11,7 @@ import { ScriptedProcessRunner, type Filesystem, } from "../../ports/index.js"; +import type { IosDriverConfig } from "./definition.js"; import { IosSimctlDriver, type SlimmedFact, type SlimSkippedFact } from "./index.js"; import { memorySourceDatabase } from "./testing.js"; @@ -85,10 +86,7 @@ export async function plantManagedDevice(filesystem: Filesystem): Promise export async function createSlimDriver( runner: ScriptedProcessRunner, filesystem: Filesystem, - slim: { - readonly categories?: readonly string[]; - readonly bootTimeoutMs: number; - }, + slim: IosDriverConfig["slim"], onSlimmed?: (fact: SlimmedFact) => void, onSlimSkipped?: (fact: SlimSkippedFact) => void, slimByDefault = false, From 9460997a22035506b30628c19b2a49b0b4c8595e Mon Sep 17 00:00:00 2001 From: Szymon Chmal Date: Tue, 17 Nov 2026 11:35:30 +0100 Subject: [PATCH 02/15] feat(ios): a slim device turns off the services the worker excludes (#1650) --- src/drivers/ios/slim-boot.ts | 12 ++++++++---- src/drivers/ios/slim-labels.ts | 25 +++++++++++++++++++++---- 2 files changed, 29 insertions(+), 8 deletions(-) diff --git a/src/drivers/ios/slim-boot.ts b/src/drivers/ios/slim-boot.ts index f2c3ef028..84f6eea02 100644 --- a/src/drivers/ios/slim-boot.ts +++ b/src/drivers/ios/slim-boot.ts @@ -160,7 +160,7 @@ export class SlimBoot { ): Promise { const configured = resolveSlimCategories(slim.categories); const { kept, resolved } = splitByExcept(configured, except); - if (configured.categories.length === 0) { + if (configured.categories.length === 0 && (slim.exclude ?? []).length === 0) { return { detail: `none of the configured slim categories (${(slim.categories ?? []).join(", ")}) are known`, kind: "no-categories", @@ -168,7 +168,11 @@ export class SlimBoot { } const startedAt = this.#clock.now(); - const wanted = overridesFor(resolved.categories, kept); + const wanted = overridesFor(resolved.categories, kept, { + exclude: slim.exclude ?? [], + include: slim.include ?? [], + recorded: [], + }); let writeError: string | undefined; try { const folder = this.#overridesFolder(udid); @@ -242,8 +246,8 @@ export class SlimBoot { return this.#skipApply(device, data, details.join("; "), "slim"); } - // why: an except list naming the whole slim set slims nothing: full, no `device.slimmed`. - if (write.resolved.categories.length === 0) return this.#asIs(device, data, "full"); + // why: nothing written off (an except list naming the whole slim set, or an include covering it) slims nothing: full, no `device.slimmed` (ADR 0083 §4). + if (![...write.wanted.values()].some(Boolean)) return this.#asIs(device, data, "full"); this.#reportSlimmed(device, data, write); return this.#asIs(device, data, "slim"); } diff --git a/src/drivers/ios/slim-labels.ts b/src/drivers/ios/slim-labels.ts index 8d75b0eed..e40f0cdee 100644 --- a/src/drivers/ios/slim-labels.ts +++ b/src/drivers/ios/slim-labels.ts @@ -341,23 +341,40 @@ export const NEVER_DISABLE_LABELS: readonly string[] = [ "com.apple.sharingd", ]; +export interface NamedServices { + readonly include: readonly string[]; + readonly exclude: readonly string[]; + readonly recorded: readonly string[]; +} + /** - * why: Every managed label (all categories plus the never-disable labels) mapped to what the overrides - * file must say: `true` (off) for a label of a configured category, `false` for the rest and for - * every label of a kept category. + * why: Every managed label (all categories, the never-disable labels and the worker's named + * services) mapped to what the overrides file must say, last rule wins (ADR 0083 S1): `false` + * for all; `true` for a label of a configured category (never-disable labels excepted); `true` + * for an `exclude` name; `false` for an `include` name and for every label of a kept category. */ export function overridesFor( categories: readonly SlimCategory[], keep: readonly SlimCategory[] = [], + named: NamedServices = { exclude: [], include: [], recorded: [] }, ): ReadonlyMap { const wanted = new Map(); for (const category of SLIM_CATEGORIES) { for (const label of category.labels) wanted.set(label, false); } - for (const label of NEVER_DISABLE_LABELS) wanted.set(label, false); + for (const label of [ + ...NEVER_DISABLE_LABELS, + ...named.recorded, + ...named.include, + ...named.exclude, + ]) { + wanted.set(label, false); + } for (const label of labelsFor(categories)) { if (!NEVER_DISABLE_LABELS.includes(label)) wanted.set(label, true); } + for (const label of named.exclude) wanted.set(label, true); + for (const label of named.include) wanted.set(label, false); // why: an excepted category wins over a slimmed one that lists the same label (ADR 0066 §2). for (const label of labelsFor(keep)) wanted.set(label, false); return wanted; From ec876f1fa9dbc1ba787824e6143fcfad513e9f2b Mon Sep 17 00:00:00 2001 From: Szymon Chmal Date: Tue, 17 Nov 2026 11:36:39 +0100 Subject: [PATCH 03/15] test: a slim prepare writes each managed label by the precedence of the named services (#1650) --- src/drivers/ios/slim-named-services.test.ts | 62 +++++++++++++++++++-- src/drivers/ios/test-slim.ts | 20 ++++++- 2 files changed, 76 insertions(+), 6 deletions(-) diff --git a/src/drivers/ios/slim-named-services.test.ts b/src/drivers/ios/slim-named-services.test.ts index 34cab2b35..ab9fefccf 100644 --- a/src/drivers/ios/slim-named-services.test.ts +++ b/src/drivers/ios/slim-named-services.test.ts @@ -1,16 +1,19 @@ import { describe, expect, it, vi } from "vitest"; -import { FakeClock, ScriptedProcessRunner } from "../../ports/index.js"; +import { FakeClock, ScriptedProcessRunner, type Logger } from "../../ports/index.js"; import type { IosDriverConfig } from "./definition.js"; import type { SlimmedFact, SlimSkippedFact } from "./index.js"; import { createSlimDriver, driverData, FaultyFilesystem, + overridesFolder, overridesPath, + overridesPlist, parseOverrides, plantManagedDevice, printDisabled, + recordPath, slimBootCalls, } from "./test-slim.js"; @@ -19,17 +22,39 @@ const diagnosticd = "com.apple.diagnosticd"; async function boot(options: { readonly slim: Omit; - readonly readback: Readonly>; + readonly readback?: Readonly>; readonly except?: readonly string[]; + readonly plist?: Readonly>; + readonly record?: string; + readonly failing?: FaultyFilesystem["failing"]; }) { const filesystem = new FaultyFilesystem(); await plantManagedDevice(filesystem); + if (options.plist !== undefined || options.record !== undefined) { + await filesystem.mkdirp(overridesFolder(slim18_5.udid)); + } + if (options.plist !== undefined) { + await filesystem.writeFileAtomic(overridesPath(slim18_5.udid), overridesPlist(options.plist)); + } + if (options.record !== undefined) { + await filesystem.writeFileAtomic(recordPath(slim18_5.udid), options.record); + } + filesystem.writes.length = 0; + if (options.failing !== undefined) filesystem.failing = options.failing; + const warn = vi.fn<(message: string) => void>(); + const logger: Logger = { + debug: () => {}, + error: () => {}, + info: () => {}, + warn, + child: () => logger, + }; const calls = slimBootCalls(slim18_5.udid, ""); const runner = new ScriptedProcessRunner([ ...calls.slice(0, 3), { match: calls[3]!.match, - result: { code: 0, stderr: "", stdout: printDisabled(options.readback) }, + result: { code: 0, stderr: "", stdout: printDisabled(options.readback ?? {}) }, }, ]); const onSlimmed = vi.fn<(fact: SlimmedFact) => void>(); @@ -42,6 +67,7 @@ async function boot(options: { onSlimSkipped, false, new FakeClock(), + logger, ); const outcome = await driver .makeReady( @@ -56,7 +82,10 @@ async function boot(options: { const written = (await filesystem.exists(file)) ? parseOverrides(await filesystem.readFile(file)) : undefined; - return { onSlimSkipped, onSlimmed, outcome, written }; + const record = (await filesystem.exists(recordPath(slim18_5.udid))) + ? (JSON.parse(await filesystem.readFile(recordPath(slim18_5.udid))) as unknown) + : undefined; + return { filesystem, onSlimSkipped, onSlimmed, outcome, record, warn, written }; } describe("IosSimctlDriver makeReady with include and exclude names", () => { @@ -72,3 +101,28 @@ describe("IosSimctlDriver makeReady with include and exclude names", () => { ); }); }); + +describe("IosSimctlDriver makeReady writes the managed labels of a slim device", () => { + const apsd = "com.apple.apsd"; + const passd = "com.apple.passd"; + const gamed = "com.apple.gamed"; + + it("writes each managed label as the precedence of the named services says, and keeps the record of the names", async () => { + const included = await boot({ slim: { include: [apsd] } }); + expect(included.written?.[apsd]).toBe(false); + expect(included.written?.[passd]).toBe(true); + + const excluded = await boot({ slim: { exclude: [diagnosticd, gamed] } }); + expect(excluded.written?.[diagnosticd]).toBe(true); + expect(excluded.written?.[gamed]).toBe(true); + expect(excluded.record).toEqual([diagnosticd, gamed]); + expect(excluded.filesystem.modes.record).toBe(0o644); + + const kept = await boot({ slim: { exclude: [apsd] }, except: ["store"] }); + expect(kept.written?.[apsd]).toBe(false); + + const unmanaged = await boot({ slim: {}, plist: { "com.example.unmanaged": true } }); + expect(unmanaged.written?.["com.example.unmanaged"]).toBe(true); + expect(unmanaged.written?.[passd]).toBe(true); + }); +}); diff --git a/src/drivers/ios/test-slim.ts b/src/drivers/ios/test-slim.ts index 9b81717af..2bd7ecd93 100644 --- a/src/drivers/ios/test-slim.ts +++ b/src/drivers/ios/test-slim.ts @@ -10,6 +10,7 @@ import { MemoryFilesystem, ScriptedProcessRunner, type Filesystem, + type Logger, } from "../../ports/index.js"; import type { IosDriverConfig } from "./definition.js"; import { IosSimctlDriver, type SlimmedFact, type SlimSkippedFact } from "./index.js"; @@ -91,6 +92,7 @@ export async function createSlimDriver( onSlimSkipped?: (fact: SlimSkippedFact) => void, slimByDefault = false, clock = new FakeClock(), + logger?: Logger, ): Promise { return await IosSimctlDriver.create({ database: await memorySourceDatabase(), @@ -102,6 +104,7 @@ export async function createSlimDriver( idGenerator: { generate: () => "device-1" }, ...(onSlimmed === undefined ? {} : { onSlimmed }), ...(onSlimSkipped === undefined ? {} : { onSlimSkipped }), + ...(logger === undefined ? {} : { logger }), launchdOverridesRoot: overridesRoot, processRunner: runner, config: { slim }, @@ -119,6 +122,11 @@ export function overridesPath(udid: string): string { return `${overridesFolder(udid)}/disabled.plist`; } +/** why: ADR 0083 S2: the record of named services sits beside the overrides file. */ +export function recordPath(udid: string): string { + return `${overridesFolder(udid)}/simlock-managed.json`; +} + export function overridesPlist(entries: Readonly>): string { const lines = Object.entries(entries).map( ([label, off]) => `${label}<${String(off)}/>`, @@ -129,8 +137,12 @@ export function overridesPlist(entries: Readonly>): stri /** why: Records what is written and fails the one operation a test names, as a full or unwritable store would. */ export class FaultyFilesystem extends MemoryFilesystem { readonly writes: string[] = []; - readonly modes: { folder?: number | undefined; file?: number | undefined } = {}; - failing: "writeFileAtomic" | "mkdirp" | "rm" | "copyFile" | undefined; + readonly modes: { + folder?: number | undefined; + file?: number | undefined; + record?: number | undefined; + } = {}; + failing: "writeFileAtomic" | "writeRecord" | "mkdirp" | "rm" | "copyFile" | undefined; failureMessage = "disk full"; override async writeFileAtomic( @@ -141,9 +153,13 @@ export class FaultyFilesystem extends MemoryFilesystem { if (this.failing === "writeFileAtomic" && path.endsWith("disabled.plist")) { throw new Error(this.failureMessage); } + if (this.failing === "writeRecord" && path.endsWith("simlock-managed.json")) { + throw new Error(this.failureMessage); + } await super.writeFileAtomic(path, contents, options); this.writes.push(path); if (path.endsWith("disabled.plist")) this.modes.file = options?.mode; + if (path.endsWith("simlock-managed.json")) this.modes.record = options?.mode; } override async mkdirp(path: string, options?: Parameters[1]) { From c0847018c02448ce9ba7d0538306a1bd26e79ffd Mon Sep 17 00:00:00 2001 From: Szymon Chmal Date: Tue, 17 Nov 2026 11:36:51 +0100 Subject: [PATCH 04/15] feat(ios): a slim prepare records the named services it wrote (#1650) --- src/drivers/ios/slim-boot.ts | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/src/drivers/ios/slim-boot.ts b/src/drivers/ios/slim-boot.ts index 84f6eea02..0688c2719 100644 --- a/src/drivers/ios/slim-boot.ts +++ b/src/drivers/ios/slim-boot.ts @@ -23,6 +23,8 @@ import { type IosDriverData } from "./simulator-data.js"; // why: ADR 0060 §2: simslim's limit for a simulator just after its first boot. const READBACK_TIMEOUT_MS = 120_000; const OVERRIDES_FILE_NAME = "disabled.plist"; +// why: ADR 0083 S2: the names the worker's `include` and `exclude` held at the last write. +const RECORD_FILE_NAME = "simlock-managed.json"; export const DEFAULT_OVERRIDES_ROOT = "/private/var/tmp"; const OVERRIDES_FOLDER_PREFIX = "com.apple.CoreSimulator.SimDevice."; @@ -183,6 +185,15 @@ export class SlimBoot { await this.#filesystem.mkdirp(folder, { mode: 0o700 }); await this.#filesystem.writeFileAtomic(file, renderOverridesPlist(merged), { mode: 0o644 }); } + const names = [...new Set([...(slim.include ?? []), ...(slim.exclude ?? [])])].sort(); + if (names.length > 0) { + await this.#filesystem.mkdirp(folder, { mode: 0o700 }); + await this.#filesystem.writeFileAtomic( + join(folder, RECORD_FILE_NAME), + JSON.stringify(names), + { mode: 0o644 }, + ); + } } catch (error: unknown) { writeError = `could not write the launchd overrides file: ${errorMessage(error)}`; } From 66cec59686fe31947388540568cf7e8453d250b9 Mon Sep 17 00:00:00 2001 From: Szymon Chmal Date: Tue, 17 Nov 2026 11:37:10 +0100 Subject: [PATCH 05/15] test: a recorded name in neither list is written back on and the record is rewritten (#1650) --- src/drivers/ios/slim-named-services.test.ts | 57 +++++++++++++++++++++ 1 file changed, 57 insertions(+) diff --git a/src/drivers/ios/slim-named-services.test.ts b/src/drivers/ios/slim-named-services.test.ts index ab9fefccf..df7acca38 100644 --- a/src/drivers/ios/slim-named-services.test.ts +++ b/src/drivers/ios/slim-named-services.test.ts @@ -124,5 +124,62 @@ describe("IosSimctlDriver makeReady writes the managed labels of a slim device", const unmanaged = await boot({ slim: {}, plist: { "com.example.unmanaged": true } }); expect(unmanaged.written?.["com.example.unmanaged"]).toBe(true); expect(unmanaged.written?.[passd]).toBe(true); + + const dropped = await boot({ + slim: { exclude: [gamed] }, + plist: { [diagnosticd]: true }, + record: JSON.stringify([diagnosticd, gamed]), + }); + expect(dropped.written?.[diagnosticd]).toBe(false); + expect(dropped.written?.[gamed]).toBe(true); + expect(dropped.record).toEqual([gamed]); + + const none = await boot({ slim: { exclude: [gamed] } }); + expect(none.warn).not.toHaveBeenCalled(); + expect(none.record).toEqual([gamed]); + + const unreadable = await boot({ + slim: { exclude: [gamed] }, + plist: { [diagnosticd]: true }, + record: "{not a list", + }); + expect(unreadable.warn).toHaveBeenCalledWith( + expect.stringContaining("could not read the record of named services"), + ); + expect(unreadable.written?.[diagnosticd]).toBe(true); + expect(unreadable.record).toEqual([gamed]); + + const wrongShape = await boot({ + slim: { exclude: [gamed] }, + record: JSON.stringify([1, 2]), + }); + expect(wrongShape.warn).toHaveBeenCalledTimes(1); + + const unchanged = await boot({ + slim: { exclude: [gamed] }, + plist: { [gamed]: true }, + record: JSON.stringify([gamed]), + }); + expect(unchanged.filesystem.writes).toEqual([]); + + const emptyNeverWritten = await boot({ slim: {} }); + expect(emptyNeverWritten.record).toBeUndefined(); + expect(emptyNeverWritten.warn).not.toHaveBeenCalled(); + }); + + it("counts a failed record write as a failed overrides write", async () => { + const failed = await boot({ + slim: { categories: [], exclude: [diagnosticd] }, + readback: { [diagnosticd]: "disabled" }, + failing: "writeRecord", + }); + expect(failed.outcome).toEqual({ result: expect.objectContaining({ mode: "slim" }) }); + expect(failed.onSlimSkipped).toHaveBeenCalledWith( + expect.objectContaining({ + detail: "could not write the launchd overrides file: disk full", + reason: "apply-failed", + }), + ); + expect(failed.onSlimmed).not.toHaveBeenCalled(); }); }); From ff72879362e29e32ada995d484c653a6e51437a6 Mon Sep 17 00:00:00 2001 From: Szymon Chmal Date: Tue, 17 Nov 2026 11:37:20 +0100 Subject: [PATCH 06/15] feat(ios): a recorded name no list holds any more goes back on at the next prepare (#1650) --- src/drivers/ios/slim-boot.ts | 33 ++++++++++++++++++++++++--------- 1 file changed, 24 insertions(+), 9 deletions(-) diff --git a/src/drivers/ios/slim-boot.ts b/src/drivers/ios/slim-boot.ts index 0688c2719..a0b32d456 100644 --- a/src/drivers/ios/slim-boot.ts +++ b/src/drivers/ios/slim-boot.ts @@ -170,14 +170,17 @@ export class SlimBoot { } const startedAt = this.#clock.now(); + const folder = this.#overridesFolder(udid); + const recordFile = join(folder, RECORD_FILE_NAME); + const names = [...new Set([...(slim.include ?? []), ...(slim.exclude ?? [])])].sort(); + const recorded = await this.#readRecord(recordFile); const wanted = overridesFor(resolved.categories, kept, { exclude: slim.exclude ?? [], include: slim.include ?? [], - recorded: [], + recorded, }); let writeError: string | undefined; try { - const folder = this.#overridesFolder(udid); const file = join(folder, OVERRIDES_FILE_NAME); const existing = await this.#readOverrides(file); const merged = new Map([...existing, ...wanted]); @@ -185,14 +188,9 @@ export class SlimBoot { await this.#filesystem.mkdirp(folder, { mode: 0o700 }); await this.#filesystem.writeFileAtomic(file, renderOverridesPlist(merged), { mode: 0o644 }); } - const names = [...new Set([...(slim.include ?? []), ...(slim.exclude ?? [])])].sort(); - if (names.length > 0) { + if (JSON.stringify(names) !== JSON.stringify(recorded)) { await this.#filesystem.mkdirp(folder, { mode: 0o700 }); - await this.#filesystem.writeFileAtomic( - join(folder, RECORD_FILE_NAME), - JSON.stringify(names), - { mode: 0o644 }, - ); + await this.#filesystem.writeFileAtomic(recordFile, JSON.stringify(names), { mode: 0o644 }); } } catch (error: unknown) { writeError = `could not write the launchd overrides file: ${errorMessage(error)}`; @@ -201,6 +199,23 @@ export class SlimBoot { return { kept, kind: "written", resolved, startedAt, wanted, writeError }; } + // why: ADR 0083 S2: a record that is missing or cannot be read as a list of strings is an empty one, so an old simulator or a damaged file never fails a boot. + async #readRecord(file: string): Promise { + try { + if (!(await this.#filesystem.exists(file))) return []; + const parsed: unknown = JSON.parse(await this.#filesystem.readFile(file)); + if (Array.isArray(parsed) && parsed.every((name) => typeof name === "string")) { + return parsed as string[]; + } + throw new Error("it is not a list of strings"); + } catch (error: unknown) { + this.#logger?.warn( + `could not read the record of named services ${file}: ${errorMessage(error)}`, + ); + return []; + } + } + async #readOverrides(file: string): Promise> { if (!(await this.#filesystem.exists(file))) return new Map(); const parsed = parseOverridesPlist(await this.#filesystem.readFile(file)); From 5bec6b0b508e26289651e7ad92c9ac4ec5be9333 Mon Sep 17 00:00:00 2001 From: Szymon Chmal Date: Tue, 17 Nov 2026 11:37:28 +0100 Subject: [PATCH 07/15] feat(ios): a recorded name no list holds any more goes back on at the next prepare (#1650) --- src/drivers/ios/slim-named-services.test.ts | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/src/drivers/ios/slim-named-services.test.ts b/src/drivers/ios/slim-named-services.test.ts index df7acca38..2c5a35221 100644 --- a/src/drivers/ios/slim-named-services.test.ts +++ b/src/drivers/ios/slim-named-services.test.ts @@ -160,7 +160,8 @@ describe("IosSimctlDriver makeReady writes the managed labels of a slim device", plist: { [gamed]: true }, record: JSON.stringify([gamed]), }); - expect(unchanged.filesystem.writes).toEqual([]); + expect(unchanged.filesystem.writes).toContain(overridesPath(slim18_5.udid)); + expect(unchanged.filesystem.writes).not.toContain(recordPath(slim18_5.udid)); const emptyNeverWritten = await boot({ slim: {} }); expect(emptyNeverWritten.record).toBeUndefined(); From 8007aa841dc0f2a7edc76824e7e47eb4ab5f8d82 Mon Sep 17 00:00:00 2001 From: Szymon Chmal Date: Tue, 17 Nov 2026 11:37:43 +0100 Subject: [PATCH 08/15] test: a provisioned copy gets its source's record of named services with its plist (#1650) --- src/drivers/ios/index-save-source-lifecycle.test.ts | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/src/drivers/ios/index-save-source-lifecycle.test.ts b/src/drivers/ios/index-save-source-lifecycle.test.ts index 8e1d87ca1..e442cb6e7 100644 --- a/src/drivers/ios/index-save-source-lifecycle.test.ts +++ b/src/drivers/ios/index-save-source-lifecycle.test.ts @@ -11,6 +11,7 @@ import { plantManagedDevice, overridesFolder, overridesPath, + recordPath, overridesPlist, FaultyFilesystem, instanceId, @@ -183,7 +184,7 @@ describe("IosSimctlDriver", () => { it.each([ { - name: "copies the seed's disabled.plist to the new simulator", + name: "copies the seed's disabled.plist and its record of named services to the new simulator", seedHas: true, failing: undefined, }, @@ -199,6 +200,7 @@ describe("IosSimctlDriver", () => { if (seedHas) { await filesystem.mkdirp(overridesFolder(seedUdid)); await filesystem.writeFileAtomic(overridesPath(seedUdid), overridesPlist({ "a.b": true })); + await filesystem.writeFileAtomic(recordPath(seedUdid), '["a.b"]'); } await plantLaunchServices(filesystem, `${deviceRoot}/${driverData.udid}`); filesystem.failing = failing; @@ -233,7 +235,9 @@ describe("IosSimctlDriver", () => { ).toEqual(["com.apple.LaunchServices.unregisteredtypes-501.db"]); const copied = failing === undefined && seedHas; expect(await filesystem.exists(overridesPath(driverData.udid))).toBe(copied); + expect(await filesystem.exists(recordPath(driverData.udid))).toBe(copied); if (copied) { + expect(await filesystem.readFile(recordPath(driverData.udid))).toBe('["a.b"]'); expect(await filesystem.readFile(overridesPath(driverData.udid))).toBe( overridesPlist({ "a.b": true }), ); From 6b60c41b0f6456f41b8d384044792c3b3eca6d5e Mon Sep 17 00:00:00 2001 From: Szymon Chmal Date: Tue, 17 Nov 2026 11:37:49 +0100 Subject: [PATCH 09/15] feat(ios): a copy of a simulator gets its source's record of named services (#1650) --- src/drivers/ios/slim-boot.ts | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/src/drivers/ios/slim-boot.ts b/src/drivers/ios/slim-boot.ts index a0b32d456..10af3d387 100644 --- a/src/drivers/ios/slim-boot.ts +++ b/src/drivers/ios/slim-boot.ts @@ -139,6 +139,13 @@ export class SlimBoot { from, join(this.#overridesFolder(copyUdid), OVERRIDES_FILE_NAME), ); + const record = join(this.#overridesFolder(seedUdid), RECORD_FILE_NAME); + if (await this.#filesystem.exists(record)) { + await this.#filesystem.copyFile( + record, + join(this.#overridesFolder(copyUdid), RECORD_FILE_NAME), + ); + } } catch (error: unknown) { this.#logger?.warn( `could not copy the launchd overrides of seed ${seedUdid} to ${copyUdid}: ${errorMessage(error)}`, From 7bf336f5b775b269d0e8e1c1e1fbdd80fd14209f Mon Sep 17 00:00:00 2001 From: Szymon Chmal Date: Tue, 17 Nov 2026 11:38:21 +0100 Subject: [PATCH 10/15] test: the readback grants the mode of the named services and a lease fails only on its kept categories (#1650) --- src/drivers/ios/slim-named-services.test.ts | 112 +++++++++++++++++++- 1 file changed, 109 insertions(+), 3 deletions(-) diff --git a/src/drivers/ios/slim-named-services.test.ts b/src/drivers/ios/slim-named-services.test.ts index 2c5a35221..af578c40a 100644 --- a/src/drivers/ios/slim-named-services.test.ts +++ b/src/drivers/ios/slim-named-services.test.ts @@ -1,8 +1,9 @@ import { describe, expect, it, vi } from "vitest"; +import { KeptCategoriesError } from "../../core/index.js"; import { FakeClock, ScriptedProcessRunner, type Logger } from "../../ports/index.js"; import type { IosDriverConfig } from "./definition.js"; -import type { SlimmedFact, SlimSkippedFact } from "./index.js"; +import { SLIM_CATEGORIES, type SlimmedFact, type SlimSkippedFact } from "./index.js"; import { createSlimDriver, driverData, @@ -19,10 +20,25 @@ import { const slim18_5 = { ...driverData, runtimeId: "com.apple.CoreSimulator.SimRuntime.iOS-18-5" }; const diagnosticd = "com.apple.diagnosticd"; +// why: spelled out, not imported: the labels simslim never disables (ADR 0060 §1). +const neverDisabled = ["com.apple.assistantd", "com.apple.gamed", "com.apple.sharingd"]; + +/** why: What launchd prints once the worker's categories and the named services are off. */ +function disabledReadback( + categories: readonly string[], + off: readonly string[], + on: readonly string[] = [], +): Record { + const labels = SLIM_CATEGORIES.filter((category) => categories.includes(category.name)) + .flatMap((category) => category.labels) + .filter((label) => !neverDisabled.includes(label) && !on.includes(label)); + return Object.fromEntries([...labels, ...off].map((label) => [label, "disabled"])); +} async function boot(options: { readonly slim: Omit; readonly readback?: Readonly>; + readonly readbackFails?: boolean; readonly except?: readonly string[]; readonly plist?: Readonly>; readonly record?: string; @@ -54,7 +70,10 @@ async function boot(options: { ...calls.slice(0, 3), { match: calls[3]!.match, - result: { code: 0, stderr: "", stdout: printDisabled(options.readback ?? {}) }, + result: + options.readbackFails === true + ? { code: 1, stderr: "boom\n", stdout: "" } + : { code: 0, stderr: "", stdout: printDisabled(options.readback ?? {}) }, }, ]); const onSlimmed = vi.fn<(fact: SlimmedFact) => void>(); @@ -89,16 +108,103 @@ async function boot(options: { } describe("IosSimctlDriver makeReady with include and exclude names", () => { + const apsd = "com.apple.apsd"; + const everyCategory = SLIM_CATEGORIES.map((category) => category.name); + const slimMode = { result: expect.objectContaining({ mode: "slim" }) }; + const fullMode = { result: expect.objectContaining({ mode: "full" }) }; + it("grants the mode the readback shows for the named services", async () => { const excludeOnly = await boot({ slim: { categories: [], exclude: [diagnosticd] }, readback: { [diagnosticd]: "disabled" }, }); expect(excludeOnly.written?.[diagnosticd]).toBe(true); - expect(excludeOnly.outcome).toEqual({ result: expect.objectContaining({ mode: "slim" }) }); + expect(excludeOnly.outcome).toEqual(slimMode); expect(excludeOnly.onSlimmed).toHaveBeenCalledWith( expect.objectContaining({ categories: [], labelCount: 1 }), ); + + const all = disabledReadback(everyCategory, [diagnosticd]); + const asWritten = await boot({ slim: { exclude: [diagnosticd] }, readback: all }); + expect(asWritten.outcome).toEqual(slimMode); + expect(asWritten.onSlimmed).toHaveBeenCalledWith( + expect.objectContaining({ categories: everyCategory, labelCount: Object.keys(all).length }), + ); + + const excludeEnabled = await boot({ + slim: { exclude: [diagnosticd] }, + readback: { ...all, [diagnosticd]: "enabled" }, + }); + expect(excludeEnabled.outcome).toEqual(fullMode); + expect(excludeEnabled.onSlimmed).not.toHaveBeenCalled(); + expect(excludeEnabled.onSlimSkipped).toHaveBeenCalledWith( + expect.objectContaining({ + detail: expect.stringContaining( + `managed labels did not read back as written at boot; first: ${diagnosticd}`, + ), + }), + ); + + const includeDisabled = await boot({ + slim: { include: [apsd] }, + readback: disabledReadback(everyCategory, []), + }); + expect(includeDisabled.outcome).toEqual(fullMode); + expect(includeDisabled.onSlimmed).not.toHaveBeenCalled(); + + const readbackFails = await boot({ slim: { exclude: [diagnosticd] }, readbackFails: true }); + expect(readbackFails.outcome).toEqual(slimMode); + expect(readbackFails.onSlimSkipped).toHaveBeenCalledWith( + expect.objectContaining({ + detail: "could not read back the launchd overrides: exit 1: boom", + }), + ); + + const nothingOff = await boot({ + slim: { + categories: ["store"], + include: SLIM_CATEGORIES.find((c) => c.name === "store")!.labels, + }, + }); + expect(nothingOff.outcome).toEqual(fullMode); + expect(nothingOff.onSlimmed).not.toHaveBeenCalled(); + + const exceptCoversSet = await boot({ slim: { categories: ["store"] }, except: ["store"] }); + expect(exceptCoversSet.outcome).toEqual(fullMode); + expect(exceptCoversSet.onSlimmed).not.toHaveBeenCalled(); + + const noCategories = await boot({ slim: { categories: [] } }); + expect(noCategories.outcome).toEqual(fullMode); + expect(noCategories.written).toBeUndefined(); + expect(noCategories.onSlimSkipped).toHaveBeenCalledWith( + expect.objectContaining({ reason: "apply-failed" }), + ); + }); + + it("fails a lease's boot only on its kept categories", async () => { + const storeLabels = SLIM_CATEGORIES.find((category) => category.name === "store")!.labels; + const keptLabel = storeLabels[0]!; + const base = disabledReadback(everyCategory, [diagnosticd], storeLabels); + const slim = { exclude: [diagnosticd] }; + + const kept = await boot({ slim, except: ["store"], readback: base }); + expect(kept.outcome).toEqual(slimMode); + + const keptDisabled = await boot({ + slim, + except: ["store"], + readback: { ...base, [keptLabel]: "disabled" }, + }); + expect(keptDisabled.outcome).toEqual({ + error: new KeptCategoriesError(`1 kept labels are not enabled; first: ${keptLabel}`), + }); + + const excludeEnabled = await boot({ + slim, + except: ["store"], + readback: { ...base, [diagnosticd]: "enabled" }, + }); + expect(excludeEnabled.outcome).toEqual(fullMode); }); }); From 8f0a9cfbc4a996760088cbb714776c45ee63379d Mon Sep 17 00:00:00 2001 From: Szymon Chmal Date: Tue, 17 Nov 2026 11:38:56 +0100 Subject: [PATCH 11/15] test: a worker config loads include and exclude lists and refuses a name in both (#1650) --- src/drivers/ios/definition.test.ts | 45 +++++++++++++++++++++++++++++- 1 file changed, 44 insertions(+), 1 deletion(-) diff --git a/src/drivers/ios/definition.test.ts b/src/drivers/ios/definition.test.ts index 6ca054770..d86b68946 100644 --- a/src/drivers/ios/definition.test.ts +++ b/src/drivers/ios/definition.test.ts @@ -6,7 +6,7 @@ import { iosDriverConfig } from "./definition.js"; const configPath = "/home/agent/.simlock/config.json"; -async function load(file: unknown) { +async function load(file: unknown, overrides?: unknown) { const filesystem = new MemoryFilesystem(); const warn = vi.fn(); await filesystem.mkdirp("/home/agent/.simlock"); @@ -17,6 +17,7 @@ async function load(file: unknown) { filesystem, systemStats: new FakeSystemStats({ cpuCount: 8, totalRamBytes: 32 * 1024 ** 3 }), warn, + ...(overrides === undefined ? {} : { overrides: overrides as never }), }); return { section: driverConfig(config, iosDriverConfig), warn }; } @@ -77,3 +78,45 @@ describe("the iOS driver's keys of the ios config section", () => { expect(section.simulator).toEqual({ audio: true, createTimeoutMs: 30_000, headless: true }); }); }); + +describe("the iOS driver's ios.slim.include and ios.slim.exclude", () => { + const bothLists = (names: string) => + `Invalid config value for "ios.slim": expected no service in both include and exclude (${names})`; + + it("load as lists of service names, and fail the load for a name in both lists or a value that is no list of names", async () => { + const both = await load({ + ios: { slim: { include: ["com.apple.apsd"], exclude: ["com.apple.diagnosticd"] } }, + }); + expect(both.section.slim).toEqual({ + bootTimeoutMs: 600_000, + exclude: ["com.apple.diagnosticd"], + include: ["com.apple.apsd"], + }); + expect(both.warn).not.toHaveBeenCalled(); + expect((await load({ ios: { slim: { include: [] } } })).section.slim.include).toEqual([]); + expect((await load({ ios: { slim: { exclude: ["a", "a"] } } })).section.slim.exclude).toEqual([ + "a", + "a", + ]); + + const refused = [ + [{ ios: { slim: { include: ["x", "y"], exclude: ["y", "x", "z"] } } }, bothLists("x, y")], + [ + { ios: { slim: { include: ["x"] } } }, + bothLists("x"), + { ios: { slim: { exclude: ["x"] } } }, + ], + [ + { ios: { slim: { exclude: "com.apple.diagnosticd" } } }, + 'Invalid config value for "ios.slim.exclude": expected an array of strings', + ], + [ + { ios: { slim: { exclude: [""] } } }, + 'Invalid config value for "ios.slim.exclude": expected an array of strings', + ], + ] as const; + for (const [file, message, overrides] of refused) { + await expect(load(file, overrides), message).rejects.toThrow(message); + } + }); +}); From b7a8098e192444860065e9185705146fb45dfbbd Mon Sep 17 00:00:00 2001 From: Szymon Chmal Date: Tue, 17 Nov 2026 11:39:18 +0100 Subject: [PATCH 12/15] feat(ios): a worker config takes include and exclude lists of slim services (#1650) --- src/core/config-role-checks.ts | 17 ++++++++++++++++- src/core/config-types.ts | 2 ++ src/core/config.ts | 2 ++ src/drivers/ios/definition.ts | 16 +++++++++++++++- 4 files changed, 35 insertions(+), 2 deletions(-) diff --git a/src/core/config-role-checks.ts b/src/core/config-role-checks.ts index 8330f82f2..f9f46790b 100644 --- a/src/core/config-role-checks.ts +++ b/src/core/config-role-checks.ts @@ -4,7 +4,13 @@ import { isCapacityStrategyName, type CapacityStrategyName, } from "./capacity/index.js"; -import type { Config, DownloadPolicy, Layer, ModuleConfigEntry } from "./config-types.js"; +import type { + Config, + DownloadPolicy, + DriverConfigEntry, + Layer, + ModuleConfigEntry, +} from "./config-types.js"; import { MIN_EVENT_LOG_MAX_BYTES } from "./config-defaults.js"; import { asObject, mergeConfig, omit, pick } from "./config-helpers.js"; import { invalidValue, requireObject, type Warn } from "./validation.js"; @@ -136,6 +142,15 @@ export function runModuleChecks(config: Config, modules: readonly ModuleConfigEn } } +export function runDriverChecks( + config: Config, + driverSections: readonly DriverConfigEntry[], +): void { + for (const entry of driverSections) { + entry.check?.(config[entry.platform] as never, config); + } +} + function warnWorkerOnlySubKeys( layer: Record, section: string, diff --git a/src/core/config-types.ts b/src/core/config-types.ts index f650fd4a1..b4d107a8f 100644 --- a/src/core/config-types.ts +++ b/src/core/config-types.ts @@ -272,6 +272,8 @@ export interface DriverConfigEntry
{ simlockHome: string, settings: Readonly>, ) => Readonly>; + // why: ADR 0083 I4: runs on the merged config, after both layers, where a rule that spans keys of one section can be judged; it throws a `ConfigError`. + readonly check?: (section: never, config: Config) => void; } export interface ModuleConfigEntry { diff --git a/src/core/config.ts b/src/core/config.ts index 89deea67f..7ecca7f10 100644 --- a/src/core/config.ts +++ b/src/core/config.ts @@ -12,6 +12,7 @@ import { normalizeLayer, requireGatewayHttp, resolveStrategyName, + runDriverChecks, runModuleChecks, validateDeletedRetention, validateEventLogBounds, @@ -204,6 +205,7 @@ export function configFromLayers( validateMetricsRetention(merged); // why: a gateway reads a module's gateway keys, so a bad value stops it too. runModuleChecks(merged, modules); + runDriverChecks(merged, driverSections); if (role === "gateway") { warnWorkerOnlyKeys([fromFile, fromOverrides], warn, modules); requireGatewayHttp(merged); diff --git a/src/drivers/ios/definition.ts b/src/drivers/ios/definition.ts index cdbb35f9d..457e36b22 100644 --- a/src/drivers/ios/definition.ts +++ b/src/drivers/ios/definition.ts @@ -2,6 +2,7 @@ import { join } from "node:path"; import { booleanValue, + invalidValue, type DriverConfigEntry, objectValidator, positiveNumber, @@ -49,8 +50,21 @@ export const iosDriverConfig: DriverConfigEntry = { full: { bootTimeoutMs: 300_000 }, simulator: { audio: true, createTimeoutMs: 30_000, headless: true }, }, + // why: ADR 0083 §1: the two lists are checked on the merged config, because the file and the overrides are validated one layer at a time. + check: (section: IosDriverConfig) => { + const { exclude = [], include = [] } = section.slim; + const both = [...new Set(include.filter((name) => exclude.includes(name)))].sort(); + if (both.length > 0) { + throw invalidValue("ios.slim", `no service in both include and exclude (${both.join(", ")})`); + } + }, validators: { - slim: objectValidator({ categories: stringArray, bootTimeoutMs: positiveNumber }), + slim: objectValidator({ + categories: stringArray, + bootTimeoutMs: positiveNumber, + include: stringArray, + exclude: stringArray, + }), full: objectValidator({ bootTimeoutMs: positiveNumber }), simulator: objectValidator({ audio: booleanValue, From 27158c7c2b7d543589d2056653302fb79c378361 Mon Sep 17 00:00:00 2001 From: Szymon Chmal Date: Tue, 17 Nov 2026 11:39:46 +0100 Subject: [PATCH 13/15] docs(ios): the configuration reference, the slim guide and the manual describe include and exclude (#1650) --- docs/internal/EVENTS.md | 2 +- src/drivers/ios/AGENTS.md | 2 ++ .../docs/docs/reference/configuration.mdx | 4 +++- .../docs/using-devices/choosing-a-device.mdx | 18 ++++++++++++++++++ 4 files changed, 24 insertions(+), 2 deletions(-) diff --git a/docs/internal/EVENTS.md b/docs/internal/EVENTS.md index f783d44b6..dcf91947d 100644 --- a/docs/internal/EVENTS.md +++ b/docs/internal/EVENTS.md @@ -103,7 +103,7 @@ Simlock registry (ADR 0002, `docs/internal/adr/0002-opt-in-slim-ios-simulators.m only") is satisfied by waiting for that commit to become observable, not by waiting on a registry write: the driver writes the launchd overrides file while the simulator is shut down, boots it once, and only fires `onSlimmed` once the readback shows the overrides in force. The registry's own `device.ready` for that same boot is a separate, -later event, emitted through the normal readiness path once the driver call returns. A boot with a lease's except list (ADR 0066) reports `categories` as the smaller list (the worker's slim set minus the excepted categories), `signature` as that list's signature and `labelCount` as the labels written `true`, so a kept label that a slimmed category also lists is not counted; a boot whose smaller list is empty is granted `full` and emits none. A slim +later event, emitted through the normal readiness path once the driver call returns. A boot with a lease's except list (ADR 0066) reports `categories` as the smaller list (the worker's slim set minus the excepted categories), `signature` as that list's signature and `labelCount` as the labels written `true`, so a kept label that a slimmed category also lists is not counted and a worker's `ios.slim.exclude` name is (ADR 0083); a boot that writes no label `true` is granted `full` and emits none. A slim request on a runtime older than iOS 18.5 is resolved to a full spec before planning (ADR 0007 §4), so it never reaches a slim boot. A *skipped* slim on a slim-spec device -- its runtime id didn't parse, the overrides file could not be written, or the readback disagreed or failed -- is deliberately not an event: it isn't a fact worth putting in front of every event-bus diff --git a/src/drivers/ios/AGENTS.md b/src/drivers/ios/AGENTS.md index 52a027220..ff152e2af 100644 --- a/src/drivers/ios/AGENTS.md +++ b/src/drivers/ios/AGENTS.md @@ -18,6 +18,7 @@ Resolve and boot: - `RuntimeMissingError` is only for what a download can fix: an OS outside the device type's range, an installed runtime not paired with the type, and anything below iOS 16 are refused instead. - A boot is `simctl boot`, `bootstatus -b`, then `listapps` until it succeeds, on one deadline: bootstatus can finish before the installer accepts requests. - Slim (ADR 0060), on `prepare` of a slim spec only: the managed labels are merged into the simulator's `disabled.plist` before the boot (other entries kept; a failed write is logged and the boot goes on), and `launchctl print-disabled system` is read back after it. A label not as written returns `full`; a readback that fails returns `slim`; both call `onSlimSkipped`, logged only. Every label as written and the write ok: `slim`, and `onSlimmed` becomes `device.slimmed`. +- Named services (ADR 0083, `ios.slim.include` and `ios.slim.exclude`): every name in either list, in the record and in a category is a managed label, written in this order, last wins: `false`; `true` for a configured category's label (never-disable labels excepted) and for an `exclude` name; `false` for an `include` name and for a lease's `--except` category. `exclude` beats the never-disable list. A device is `slim` only when some label is written `true`, so `categories: []` with an `exclude` is slim and an `include` covering the slim set is `full`. An `include` or `exclude` label not read back as written grants `full`, never a throw. The record `simlock-managed.json` beside `disabled.plist` lists the names last written: a recorded name in neither list is written `false`, then the record is rewritten (an empty list with no file is not written). It is copied with the plist and removed with its folder; one that cannot be read as a list of strings is empty and logged. A failed record write is a failed overrides write. - Slim `except` (ADR 0066, `slim-except.ts`): an excepted category's labels are written `false`; an unknown name is `BAD_REQUEST`; a kept label not read back throws `KeptCategoriesError`. - A recovery boot writes no slim overrides and reads nothing back. DeviceHub clipboard isolation is configured before preparation and recovery boots; ready default-set simulators reboot under the lease claim before a grant. Active leases at upgrade keep clipboard sync until a later boot or lease end. - The overrides folder lives outside the device set (`launchdOverridesRoot`), so `destroy` removes it itself after `simctl delete`. @@ -52,6 +53,7 @@ Tunnels (`device-tcp.ts`): - **A restart between `simctl clone` and the durable mark under `default` (#968)** leaves one unlisted `simlock-` simulator in Xcode's set. Delete it with `simctl delete`. - **Runtime downloads outlive deletion (#79).** Reclaim them in Xcode → Settings → Platforms. - **Slim costs (#87, #172).** Below iOS 18.5 a slim request gets `full`. Slim devices lose push, Spotlight, StoreKit, universal links, Siri, iCloud sync; use `--mode full` for them. +- **A misspelt `include` or `exclude` name is silent**, and a baseline saved before ADR 0083 has no record: a name later dropped from `exclude` stays off in its copies until it is put in `include`. - **The overrides file is undocumented.** If Apple ignores it, the readback grants `full`. - **A recovered slim device runs full but is recorded `slim` (#174)** until its next `makeReady`. - **A cold slim lease takes a full cold boot.** MCP clients need a longer timeout. diff --git a/website/src/content/docs/docs/reference/configuration.mdx b/website/src/content/docs/docs/reference/configuration.mdx index 7e10a9049..7afff4de2 100644 --- a/website/src/content/docs/docs/reference/configuration.mdx +++ b/website/src/content/docs/docs/reference/configuration.mdx @@ -203,7 +203,9 @@ The warm pool never downloads. A gateway never asks a worker to download for a l | Key | Type | Default | Meaning | Applies to | | ---------------------------------- | ---------------------------------- | -------------------------------- | --------------------------------------------------------------------------------------------------------- | ---------- | | `ios.defaultMode` | `slim` or `full` | `full` | Device mode for an iOS request that names none. The worker makes both kinds either way. | Worker | -| `ios.slim.categories` | list of strings | every category | Which groups of simulator services a slim device has turned off: `widgets`, `siri`, `search`, `icloud`, `store`, `pim`, `web`, `family`, `health`, `photos`, `apps`, `messaging`, `connectivity`, `telemetry`, `mdm`, `other`. Narrowing the list turns the dropped services back on the next time a device is prepared. | Worker | +| `ios.slim.categories` | list of strings | every category | Which groups of simulator services a slim device has turned off: `widgets`, `siri`, `search`, `icloud`, `store`, `pim`, `web`, `family`, `health`, `photos`, `apps`, `messaging`, `connectivity`, `telemetry`, `mdm`, `other`. Narrowing the list turns the dropped services back on the next time a device is prepared. `categories` and `exclude` turn services off; `include` keeps them running. | Worker | +| `ios.slim.include` | list of strings | none | Launchd service names, such as `com.apple.apsd`, that a slim device keeps running even when a category turns them off. A name that is no service does nothing, and Simlock does not warn. A name in `exclude` too fails the config load. | Worker | +| `ios.slim.exclude` | list of strings | none | Launchd service names, such as `com.apple.diagnosticd`, that a slim device turns off beside its categories. This includes services no category holds and the three that slim never turns off (`assistantd`, `gamed`, `sharingd`). A lease's `--except` category still keeps its own services running. With `categories` set to `[]`, a list here alone makes a device slim. Removing a name turns the service back on the next time a device is prepared, except in a saved baseline made before this key existed; put the name in `include` for those. | Worker | | `ios.slim.bootTimeoutMs` | positive number | `600000` (10 min) | Boot deadline for a slim iOS device, which boots once. | Worker | | `ios.full.bootTimeoutMs` | positive number | `300000` (5 min) | Boot deadline for a full iOS device: a new device, a recovery boot and the boot that makes a seed. Counted from before `simctl boot`: the boot and `bootstatus` share it. | Worker | | `ios.defaultModels.` | model name, or non-empty list | not set | iOS models to try first for a class (`phone`, `tablet`, `watch`, `tv`, `vision`, `auto`, `desktop`), most preferred first, before Simlock's own list. A key that is not a class stops the daemon from starting. | Worker | diff --git a/website/src/content/docs/docs/using-devices/choosing-a-device.mdx b/website/src/content/docs/docs/using-devices/choosing-a-device.mdx index a99464fcb..5515301c8 100644 --- a/website/src/content/docs/docs/using-devices/choosing-a-device.mdx +++ b/website/src/content/docs/docs/using-devices/choosing-a-device.mdx @@ -141,6 +141,24 @@ The simulator boots with those categories running and the rest of the slim set o - A device the worker holds warm is shut down and booted again with your list before you get it, so the lease can take a little longer than one without `--except`. If that boot fails, the device is deleted and Simlock tries once more with another; a second failure is `PROVISION_FAILED`. - Over HTTP the body takes `except` as a list, and over MCP `lease_simulator` takes the same `except`. +### Keep or turn off single services (worker admin) + +A worker's config can name single services, beside the categories. `ios.slim.include` keeps a service running even when its category is off, and `ios.slim.exclude` turns one off, even one that no category holds: + +```jsonc +{ "ios": { "defaultMode": "slim", "slim": { + "include": ["com.apple.apsd"], + "exclude": ["com.apple.diagnosticd"] } } } +``` + +- Every slim device the worker prepares from then on boots that way. A lease changes nothing: `--except` still names categories only, and a category it keeps wins over `exclude` for its own services. +- With `categories` set to `[]`, `exclude` alone makes a device slim. A device with no service turned off is `full`. +- `exclude` also turns off the three services slim never touches (`assistantd`, `gamed`, `sharingd`). +- A name in both lists, or a list that holds anything but names, fails the config load. +- Simlock does not check that a name is a real service: a misspelling turns nothing off and keeps nothing running. +- Taking a name out of `exclude` turns the service back on at the next prepare, including in idle simulators that survive a restart. A baseline saved before this setting existed has no record of the name: put it in `include` to turn it on in that baseline's copies. +- An `include` or `exclude` service that does not read back as written grants a `full` device, as for any slim service. + ## Choose the system image (Android) `--image-tag` picks the kind of Android system image, such as `google_apis_playstore` for Google Play or `default` for plain Android. You can use the tags that `simlock catalog --platform android` lists under images. From 915e6f2af36c643b21257f96f7d5504b8ce0cced Mon Sep 17 00:00:00 2001 From: Szymon Chmal Date: Tue, 17 Nov 2026 11:40:53 +0100 Subject: [PATCH 14/15] test: a worker's exclude and include are in force on a real simulator (#1650) --- e2e/helpers/ios-device-set.ts | 11 +++++++++++ e2e/slow-ios-slim.test.ts | 37 +++++++++++++++++++++++++++++++++++ 2 files changed, 48 insertions(+) diff --git a/e2e/helpers/ios-device-set.ts b/e2e/helpers/ios-device-set.ts index 3f5b8689b..76f21dcfa 100644 --- a/e2e/helpers/ios-device-set.ts +++ b/e2e/helpers/ios-device-set.ts @@ -101,6 +101,17 @@ export async function sweepStaleDeviceSets(): Promise { } } +// why: a simulator's daemons run from the runtime's own root, not from the device set, so a service +// is found by its binary's name under a `RuntimeRoot`. +export async function runtimeRootProcesses(binary: string): Promise { + const { stdout } = await execFileAsync("ps", ["-axo", "command="], { + maxBuffer: 16 * 1024 * 1024, + }); + return stdout + .split("\n") + .filter((line) => line.includes("RuntimeRoot") && line.includes(`/usr/libexec/${binary}`)); +} + /** * Host processes whose command line names a path inside `deviceSet`. A booted simulator runs a * `launchd_sim` (and its children) out of its device directory, so a non-empty result means a diff --git a/e2e/slow-ios-slim.test.ts b/e2e/slow-ios-slim.test.ts index e43717e21..b34999cde 100644 --- a/e2e/slow-ios-slim.test.ts +++ b/e2e/slow-ios-slim.test.ts @@ -7,6 +7,7 @@ import type { TestEnv } from "./helpers/env.js"; import { iosDeviceSet, processesInDeviceSet, + runtimeRootProcesses, setDevices, simctlInSet, sweepStaleDeviceSets, @@ -442,6 +443,42 @@ describe.skipIf(process.platform !== "darwin")( }, ); + it( + "a worker's exclude turns off a service no category holds, and its include keeps a category's service running", + { timeout: 1_800_000 }, + async () => { + const diagnosticd = "com.apple.diagnosticd"; + const apsd = "com.apple.apsd"; + const excluding = await withRealDaemon({ + ios: { defaultMode: "slim", slim: { categories: [], exclude: [diagnosticd] } }, + }); + const { model, os } = await catalogModelWithOs(excluding, (versions) => + versions.find((version) => Number(version.split(".")[0]) >= 26), + ); + const excluded = await leaseDetached(excluding, model, os, "slim-exclude"); + await expectSlim(excluding, excluded.mode, "a worker with only an exclude must grant slim"); + expect((await printDisabled(excluded)).has(diagnosticd)).toBe(true); + expect( + await runtimeRootProcesses("diagnosticd"), + "no diagnosticd runs while the excluding worker's device is booted", + ).toEqual([]); + await excluding.cli(["nuke", "--delete-devices", "--yes"], { timeout: 180_000 }); + + const including = await withRealDaemon({ + ios: { defaultMode: "slim", slim: { include: [apsd] } }, + }); + const included = await leaseDetached(including, model, os, "slim-include"); + await expectSlim(including, included.mode, "a worker with only an include must grant slim"); + const disabled = await printDisabled(included); + expect(disabled.has(apsd), "apsd is kept running by include").toBe(false); + expect( + [...ALL_LABELS].filter((label) => label !== apsd && !disabled.has(label)), + "every other category label is disabled", + ).toEqual([]); + await including.cli(["nuke", "--delete-devices", "--yes"], { timeout: 180_000 }); + }, + ); + it( "no simulator from this file's device sets is still running after its flows", { timeout: 60_000 }, From 8465889fdde83aa6f3b06f5a172b942d9bc71404 Mon Sep 17 00:00:00 2001 From: Szymon Chmal Date: Tue, 17 Nov 2026 11:42:32 +0100 Subject: [PATCH 15/15] refactor(ios): the overrides and record writes are one step (#1650) --- src/drivers/ios/slim-boot.ts | 35 ++++++++++++++++++++++++----------- 1 file changed, 24 insertions(+), 11 deletions(-) diff --git a/src/drivers/ios/slim-boot.ts b/src/drivers/ios/slim-boot.ts index 10af3d387..7b177e1aa 100644 --- a/src/drivers/ios/slim-boot.ts +++ b/src/drivers/ios/slim-boot.ts @@ -188,17 +188,7 @@ export class SlimBoot { }); let writeError: string | undefined; try { - const file = join(folder, OVERRIDES_FILE_NAME); - const existing = await this.#readOverrides(file); - const merged = new Map([...existing, ...wanted]); - if (!sameEntries(existing, merged)) { - await this.#filesystem.mkdirp(folder, { mode: 0o700 }); - await this.#filesystem.writeFileAtomic(file, renderOverridesPlist(merged), { mode: 0o644 }); - } - if (JSON.stringify(names) !== JSON.stringify(recorded)) { - await this.#filesystem.mkdirp(folder, { mode: 0o700 }); - await this.#filesystem.writeFileAtomic(recordFile, JSON.stringify(names), { mode: 0o644 }); - } + await this.#writeFiles(folder, wanted, { names, recorded }); } catch (error: unknown) { writeError = `could not write the launchd overrides file: ${errorMessage(error)}`; } @@ -206,6 +196,29 @@ export class SlimBoot { return { kept, kind: "written", resolved, startedAt, wanted, writeError }; } + // why: the plist first, then the record: a restart between them leaves the old record, which still lists every name the plist may hold off (ADR 0083 S2). + async #writeFiles( + folder: string, + wanted: ReadonlyMap, + record: { readonly names: readonly string[]; readonly recorded: readonly string[] }, + ): Promise { + const file = join(folder, OVERRIDES_FILE_NAME); + const existing = await this.#readOverrides(file); + const merged = new Map([...existing, ...wanted]); + if (!sameEntries(existing, merged)) { + await this.#filesystem.mkdirp(folder, { mode: 0o700 }); + await this.#filesystem.writeFileAtomic(file, renderOverridesPlist(merged), { mode: 0o644 }); + } + if (JSON.stringify(record.names) !== JSON.stringify(record.recorded)) { + await this.#filesystem.mkdirp(folder, { mode: 0o700 }); + await this.#filesystem.writeFileAtomic( + join(folder, RECORD_FILE_NAME), + JSON.stringify(record.names), + { mode: 0o644 }, + ); + } + } + // why: ADR 0083 S2: a record that is missing or cannot be read as a list of strings is an empty one, so an old simulator or a damaged file never fails a boot. async #readRecord(file: string): Promise { try {