Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
24 commits
Select commit Hold shift + click to select a range
ff2b01e
test: a slim device is slim when only an exclude name is written off …
V3RON Nov 17, 2026
9460997
feat(ios): a slim device turns off the services the worker excludes (…
V3RON Nov 17, 2026
ec876f1
test: a slim prepare writes each managed label by the precedence of t…
V3RON Nov 17, 2026
c084701
feat(ios): a slim prepare records the named services it wrote (#1650)
V3RON Nov 17, 2026
66cec59
test: a recorded name in neither list is written back on and the reco…
V3RON Nov 17, 2026
ff72879
feat(ios): a recorded name no list holds any more goes back on at the…
V3RON Nov 17, 2026
5bec6b0
feat(ios): a recorded name no list holds any more goes back on at the…
V3RON Nov 17, 2026
8007aa8
test: a provisioned copy gets its source's record of named services w…
V3RON Nov 17, 2026
6b60c41
feat(ios): a copy of a simulator gets its source's record of named se…
V3RON Nov 17, 2026
7bf336f
test: the readback grants the mode of the named services and a lease …
V3RON Nov 17, 2026
8f0a9cf
test: a worker config loads include and exclude lists and refuses a n…
V3RON Nov 17, 2026
b7a8098
feat(ios): a worker config takes include and exclude lists of slim se…
V3RON Nov 17, 2026
27158c7
docs(ios): the configuration reference, the slim guide and the manual…
V3RON Nov 17, 2026
915e6f2
test: a worker's exclude and include are in force on a real simulator…
V3RON Nov 17, 2026
8465889
refactor(ios): the overrides and record writes are one step (#1650)
V3RON Nov 17, 2026
a94296f
Merge remote-tracking branch 'origin/feature/1644-adr' into HEAD
V3RON Nov 17, 2026
1597ae7
fix(ios): a name dropped from both lists is written back on even when…
V3RON Nov 17, 2026
a7eaf81
fix(ios): a worker with no label written off is full, and an unconfig…
V3RON Nov 17, 2026
5a0d833
fix(ios): an unconfigured slim skip keeps the write error, and the ma…
V3RON Nov 17, 2026
5d9cfc6
refactor(ios): split the slim write and readback into smaller steps (…
V3RON Nov 17, 2026
52697c2
fix(test): the slim include and exclude slow test runs both configs o…
V3RON Nov 17, 2026
54deb2a
docs(adr): accept 0083 (#1650)
V3RON Nov 17, 2026
25f726a
Merge remote-tracking branch 'origin/feature/1644-adr' into HEAD
V3RON Nov 17, 2026
4b1b328
fix(docs): the ADR index lists 0083 once (#1650)
V3RON Nov 17, 2026
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion docs/internal/EVENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# 0083. A worker may turn single slim services on or off beside its categories

- **Status:** Accepted — not yet implemented
- **Status:** Accepted
- **Date:** 2026-11-17
- **Issue:** [#1644](https://github.com/callstackincubator/simlock/issues/1644) (requests [#1556](https://github.com/callstackincubator/simlock/issues/1556), [#1552](https://github.com/callstackincubator/simlock/issues/1552))
- **Narrows:** [ADR 0060](0060-ios-slim-writes-launchd-overrides-while-the-simulator-is-shut-down.md) §1 (the managed labels gain the worker's named services and the ones it recorded, a never-disable label may be written `true`, and a record file sits beside the overrides) and §2 (a device is `slim` only when some label is written `true`); [ADR 0066](0066-a-slim-lease-may-keep-named-categories-running.md) §2 (a kept category also wins over a service the worker turns off by name).
Expand Down
2 changes: 1 addition & 1 deletion docs/internal/adr/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -115,5 +115,5 @@ the status is stale.
| [0078](0078-an-android-worker-tries-its-default-image-tag-first-and-falls-back-to-none.md) | An Android worker tries its default image tag first, and a lease falls back to none | Accepted |
| [0079](0079-one-capture-per-device-is-shared-by-every-viewer-and-every-capture-sends-a-key-frame-every-5-s.md) | One capture per device is shared by every viewer, and every capture sends a key frame at least every 5 s | Accepted; narrows 0045 §5 |
| [0080](0080-an-android-worker-may-enrol-phones-reached-over-the-network.md) | An Android worker may enrol phones reached over the network | Accepted; narrows 0022 §6 and §7, and 0073 §2 and §5 |
| [0083](0083-a-worker-may-turn-single-slim-services-on-or-off-beside-its-categories.md) | A worker may turn single slim services on or off beside its categories | Accepted — not yet implemented; narrows 0060 §1, §2 and 0066 §2 |
| [0083](0083-a-worker-may-turn-single-slim-services-on-or-off-beside-its-categories.md) | A worker may turn single slim services on or off beside its categories | Accepted; narrows 0060 §1, §2 and 0066 §2 |
| [0084](0084-a-worker-may-serve-a-platforms-enrolled-phones-only.md) | A worker may serve a platform's enrolled phones only | Accepted; narrows 0022 and 0009 §4 |
11 changes: 11 additions & 0 deletions e2e/helpers/ios-device-set.ts
Original file line number Diff line number Diff line change
Expand Up @@ -101,6 +101,17 @@ export async function sweepStaleDeviceSets(): Promise<void> {
}
}

// 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<string[]> {
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
Expand Down
40 changes: 40 additions & 0 deletions e2e/slow-ios-slim.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,7 @@ import type { TestEnv } from "./helpers/env.js";
import {
iosDeviceSet,
processesInDeviceSet,
runtimeRootProcesses,
setDevices,
simctlInSet,
sweepStaleDeviceSets,
Expand Down Expand Up @@ -442,6 +443,45 @@ 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";
// why: one lane home serves one env at a time (keepSeeds), so one daemon runs both configs in turn.
const env = await withRealDaemon({ ios: { defaultMode: "slim" } });
const { model, os } = await catalogModelWithOs(env, (versions) =>
versions.find((version) => Number(version.split(".")[0]) >= 26),
);
await env.withConfig(
{ ios: { slim: { categories: [], exclude: [diagnosticd] } } },
async () => {
const excluded = await leaseDetached(env, model, os, "slim-exclude");
await expectSlim(env, 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 env.cli(["nuke", "--delete-devices", "--yes"], { timeout: 180_000 });
},
);

await env.withConfig({ ios: { slim: { include: [apsd] } } }, async () => {
const included = await leaseDetached(env, model, os, "slim-include");
await expectSlim(env, 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 env.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 },
Expand Down
17 changes: 16 additions & 1 deletion src/core/config-role-checks.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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";
Expand Down Expand Up @@ -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<string, unknown>,
section: string,
Expand Down
2 changes: 2 additions & 0 deletions src/core/config-types.ts
Original file line number Diff line number Diff line change
Expand Up @@ -276,6 +276,8 @@ export interface DriverConfigEntry<Section = unknown> {
simlockHome: string,
settings: Readonly<Record<string, string | number | boolean>>,
) => Readonly<Record<string, string | number | boolean>>;
// 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 {
Expand Down
2 changes: 2 additions & 0 deletions src/core/config.ts
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,7 @@ import {
normalizeLayer,
requireGatewayHttp,
resolveStrategyName,
runDriverChecks,
runModuleChecks,
validateDeletedRetention,
validateEventLogBounds,
Expand Down Expand Up @@ -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);
Expand Down
23 changes: 12 additions & 11 deletions src/drivers/ios/AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -16,24 +16,25 @@ Resolve and boot:

- A slim spec is returned only for a slim request the driver will slim. The registry alone records a device's mode.
- `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`.
- 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 boot is `simctl boot`, `bootstatus -b`, then `listapps` until it succeeds, on one deadline: bootstatus can finish before the installer is ready.
- 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, the boot goes on), and `launchctl print-disabled system` is read back after it. A label not as written is `full`; a failed readback is `slim`; both call `onSlimSkipped`, logged only. All as written and the write ok: `slim`, and `onSlimmed` is `device.slimmed`. Nothing written off and no kept category: `full`, no readback.
- Named services (ADR 0083): `exclude` beats `include` beats a category; `simlock-managed.json` records the names, so one dropped from both is written back on. A baseline saved before it keeps a dropped name off; `include` it.
- Slim `except` (ADR 0066): 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`.
- After every boot and before the readback, `runAfterBoot` (`boot-courtesies.ts`) runs the volume step, then the window step. Each only reports its failure (`onSilenceFailed`, `onWindowFailed`).
- Volume (`ios.simulator.audio: false`): apps play at volume 0. A baseline source is not silenced.
- Window (`ios.simulator.headless: false`): DeviceHub is opened in the background and told not to shut down started devices when it quits. Only a non-zero exit of that open means DeviceHub is missing: Simulator.app is then opened instead, detached, so quitting it leaves the simulator running.
- Window (`ios.simulator.headless: false`): DeviceHub is opened in the background and leaves started devices running when it quits. Only a non-zero exit of that open means it is missing: Simulator.app is then opened, detached.

Seeds (ADR 0061):

- A simulator is a clone of its kind's seed. A seed is known by its `ios_source_data` row, never by name, and lives in the sources set: `sources` in the owned set, an owned root of its own under `default`. It is in no `listManaged` or `simlock simctl list`.
- A seed is made from a throwaway (ADR 0076): `simlock-seed-<id>` is booted once, shut down, cloned unbooted into the sources set, then deleted with its log folder; `saveSource` deletes the saved-from lease's log folder too. A log folder that cannot be deleted is logged and the make or save goes on; a throwaway that cannot be deleted fails the make.
- A source records its lineage and, in `ios_source_files`, the files and links naming it, after flushing its WALs. A clone keeps its source's lineage and, before its first boot, has its `com.apple.LaunchServices-*.csstore` deleted and those files and links swapped to its own UDID; a failed drop or swap deletes it. No lineage: a seed is remade, a baseline stale.
- Two provisions of a kind make one seed; clones of a seed and its deletion take turns.
- A `clone` or `create` waits `ios.simulator.createTimeoutMs`. At the limit it fails but `simctl` runs on: the UDID it later prints is deleted, the seed's deletion waits for it, and one silent 5 minutes more is killed and logged.
- A `clone` or `create` waits `ios.simulator.createTimeoutMs`. At the limit it fails but `simctl` runs on: the UDID it later prints is deleted, the seed's deletion waits for it, and 5 silent minutes more kills and logs it.
- A `making` row of another process is swept at the first `listSources`, with its throwaway; one of this process, once older than any make takes, at the next make of its kind.
- A seed that `simctl delete` calls `Invalid device` is already gone: its row is dropped. `removeComponent` deletes the runtime's seeds first.
- A seed `simctl delete` calls `Invalid device` is gone: its row is dropped. `removeComponent` deletes the runtime's seeds first.

Physical, passthrough, screen:

Expand All @@ -51,13 +52,13 @@ Tunnels (`device-tcp.ts`):

- **A restart between `simctl clone` and the durable mark under `default` (#968)** leaves one unlisted `simlock-<id>` 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.
- **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`.
- **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.
- **A screen stream can freeze after a reboot under its lease.** The capture checks the boot only at start: after a crash reboot the old picture stays until the Screen tab is reopened.
- **An iPhone's rotation has not run on hardware**; only a Duo's panel switch is proven. A silent iPhone keeps its last picture.
- **A cold slim lease takes a full cold boot;** MCP clients need a longer timeout.
- **A screen stream can freeze after a reboot under its lease:** the capture checks the boot only at start; reopen the Screen tab.
- **An iPhone's rotation has not run on hardware**; only a Duo's panel switch is proven.
- **A foldable's stream follows SpringBoard's `DisplayContentMode` log** (ADR 0075): another wording leaves it, and taps, on the panel picked at open; a tap between a fold and the new size lands on the old panel.
- **A capture killed by SIGKILL cannot stop its CoreDevice stream**, and neither can a stop while `startMediaStream` runs past its limit.
- **A new Xcode major turns iPhone streams off** until `vendor/screen-capture/Stubs/` is checked against it and the pin moves.
- **Untested on an iPhone:** DeviceHub or Xcode showing the same device during a stream; the holder's `devicectl` commands during one; the source ending after the first picture; `stop()` ending the stream.
- **Untested on an iPhone:** DeviceHub or Xcode showing the same device during a stream; the holder's `devicectl` commands during one; `stop()` ending the stream.
45 changes: 44 additions & 1 deletion src/drivers/ios/definition.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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");
Expand All @@ -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 };
}
Expand Down Expand Up @@ -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);
}
});
});
Loading
Loading