From 858a63e1237c09cf5c62198cb28ca6280f2499ef Mon Sep 17 00:00:00 2001 From: Szymon Chmal Date: Sun, 15 Nov 2026 15:45:51 +0100 Subject: [PATCH 01/34] test: iOS sources live in a folder as long as the device set, an owned root (#1569) --- src/drivers/ios/index.test.ts | 98 +++++++++++++++++++++++++++++++++++ 1 file changed, 98 insertions(+) diff --git a/src/drivers/ios/index.test.ts b/src/drivers/ios/index.test.ts index 56e52e141..88ee872be 100644 --- a/src/drivers/ios/index.test.ts +++ b/src/drivers/ios/index.test.ts @@ -5606,6 +5606,104 @@ describe("IosSimctlDriver device set", () => { }, ); + it("makes the sources folder an owned root with a path as long as the device set's, under both settings", async () => { + const xcodeSim = "/Users/al/Library/Developer/CoreSimulator"; + const cases = [ + { + name: "simlock, default root", + home: "/home/.simlock", + config: {}, + devices: "/home/.simlock/devices/ios", + sources: "/home/.simlock/devices/src", + }, + { + name: "simlock, configured deviceRoot that fits", + home: "/home/.simlock", + config: { deviceRoot: "/Volumes/simulators/devices" }, + devices: "/Volumes/simulators/devices", + sources: "/home/.simlock/devices/src_", + }, + { + name: "default under the user's home", + home: "/Users/al/.simlock", + config: { deviceSet: "default" }, + devices: `${xcodeSim}/Devices`, + sources: `/Users/al/.simlock/devices/src${"_".repeat(19)}`, + madeBeforeCreate: true, + }, + { + name: "default with SIMLOCK_HOME on another volume", + home: "/Volumes/Fast/simlock", + config: { deviceSet: "default" }, + devices: `${xcodeSim}/Devices`, + sources: `/Volumes/Fast/simlock/devices/src${"_".repeat(16)}`, + madeBeforeCreate: true, + }, + { + name: "simlock with both under /private", + home: "/private/tmp/h", + config: {}, + devices: "/private/tmp/h/devices/ios", + sources: "/private/tmp/h/devices/src", + }, + { + name: "default with Xcode's Devices not made yet", + home: "/Users/al/.simlock", + config: { deviceSet: "default" }, + devices: `${xcodeSim}/Devices`, + sources: `/Users/al/.simlock/devices/src${"_".repeat(19)}`, + }, + ] as const; + const seed = "00000000-0000-0000-0000-0000000000aa"; + const copy = "00000000-0000-0000-0000-0000000000bb"; + + for (const entry of cases) { + const scoped = !("deviceSet" in entry.config); + const step = (args: readonly (string | RegExp)[], stdout = "", anySet = true) => ({ + match: { args: ["simctl", ...(anySet ? ["--set", /.*/] : []), ...args], command: "xcrun" }, + result: { code: 0, stderr: "", stdout }, + }); + const runner = new ScriptedProcessRunner([ + step(["list", "-j", "devicetypes", "runtimes"], listFixture, scoped), + step( + ["create", "simlock-seed-device-1", driverData.deviceTypeId, driverData.runtimeId], + `${seed}\n`, + ), + step(["boot", seed]), + step(["bootstatus", seed, "-b"]), + step(["listapps", seed]), + step(["shutdown", seed]), + step(["clone", seed, /^simlock-/, entry.devices], `${copy}\n`), + ]); + const filesystem = new MemoryFilesystem(); + await filesystem.mkdirp(entry.home); + if ("madeBeforeCreate" in entry) await filesystem.mkdirp(entry.devices); + const driver = await IosSimctlDriver.create({ + database: await memorySourceDatabase(), + clock: new FakeClock(), + coreSimulatorRoot: xcodeSim, + driverConfig: entry.config, + filesystem, + idGenerator: { generate: () => "device-1" }, + instanceId, + processRunner: runner, + simlockHome: entry.home, + }); + await filesystem.mkdirp(`${entry.devices}/${copy}/data`); + + await driver.resolveSpec({ model: "iPhone 16", osVersion: "26.5", platform: "ios" }); + await driver.provision(spec); + + const sourceSets = runner.calls.slice(1).map((call) => call.args[2]); + expect(sourceSets, entry.name).toEqual(Array.from({ length: 6 }, () => entry.sources)); + expect(entry.sources.length, entry.name).toBe(entry.devices.length); + await expect( + filesystem.exists(`${entry.sources}/${OWNED_ROOT_MARKER_FILE}`), + entry.name, + ).resolves.toBe(true); + } + }); + it.each([ ["Default", { deviceSet: "Default" }, "Default", 'but it is "Default"'], ["the empty string", { deviceSet: "" }, "", 'but it is ""'], From 914083a2d4b937d9d6a48a8b537396000aede897 Mon Sep 17 00:00:00 2001 From: Szymon Chmal Date: Sun, 15 Nov 2026 15:47:13 +0100 Subject: [PATCH 02/34] feat(ios): sources live in an owned folder as long as the device set (#1569) --- src/drivers/ios/boot-courtesies.test.ts | 2 +- src/drivers/ios/index.test.ts | 56 +++++++++++++------------ src/drivers/ios/index.ts | 33 +++++++++++---- src/drivers/ios/source-data.ts | 5 --- src/drivers/ios/sources-folder.ts | 37 ++++++++++++++++ src/drivers/ios/test-slim.ts | 5 ++- src/drivers/ios/testing.ts | 2 +- 7 files changed, 98 insertions(+), 42 deletions(-) create mode 100644 src/drivers/ios/sources-folder.ts diff --git a/src/drivers/ios/boot-courtesies.test.ts b/src/drivers/ios/boot-courtesies.test.ts index 15ba96edc..6189d12b0 100644 --- a/src/drivers/ios/boot-courtesies.test.ts +++ b/src/drivers/ios/boot-courtesies.test.ts @@ -30,7 +30,7 @@ async function waitForCalls(runner: ScriptedProcessRunner, count: number): Promi } describe("IosSimctlDriver ios.simulator.headless refusal", () => { - const coreSimulatorRoot = "/CoreSim"; + const coreSimulatorRoot = "/Users/me/CoreSimulator"; it.each([ ["false with default", { deviceSet: "default" }, false, undefined], diff --git a/src/drivers/ios/index.test.ts b/src/drivers/ios/index.test.ts index 88ee872be..08b4ebf53 100644 --- a/src/drivers/ios/index.test.ts +++ b/src/drivers/ios/index.test.ts @@ -61,6 +61,7 @@ import { simctl, simctlArgs, slimBootCalls, + sourcesRoot, waitForCalls, } from "./test-slim.js"; @@ -181,12 +182,24 @@ afterEach(() => { if (call.command !== "xcrun" || call.args[0] !== "simctl") continue; if (UNSCOPED_LEGACY_CALLS.has(call.args.join(" "))) continue; expect(call.args.slice(0, 2)).toEqual(["simctl", "--set"]); - expect([deviceRoot, `${deviceRoot}/sources`]).toContain(call.args[2]); + expect([deviceRoot, sourcesRoot]).toContain(call.args[2]); } }); +/** why: Xcode's set under the tests' core-simulator root is 31 characters, so under this home the sources folder is `src` and 5 underscores. */ +const xcodeSourcesRoot = "/home/.simlock/devices/src_____"; + const seedUdid = "00000000-0000-0000-0000-0000000000aa"; +/** why: a sources folder an earlier run of this instance made, so a test can plant simulators in it. */ +async function plantOwnedRoot(filesystem: Filesystem, path: string): Promise { + await filesystem.mkdirp(path, { mode: 0o700 }); + await filesystem.writeFileAtomic( + `${path}/${OWNED_ROOT_MARKER_FILE}`, + JSON.stringify({ schemaVersion: 1, owner: "simlock", instanceId, platform: "ios" }), + ); +} + interface Catalog { devicetypes: { identifier: string }[]; runtimes: { buildversion?: string; identifier: string }[]; @@ -197,7 +210,7 @@ function sourcesSimctl(...args: readonly string[]): { readonly command: string; readonly args: string[]; } { - return { args: ["simctl", "--set", `${deviceRoot}/sources`, ...args], command: "xcrun" }; + return { args: ["simctl", "--set", sourcesRoot, ...args], command: "xcrun" }; } /** why: A database that already holds the seed of the kind `spec` names, so a test of the copy step starts at the clone. */ @@ -913,10 +926,6 @@ describe("IosSimctlDriver", () => { rowsWhenCreated, "the seed's row is making, with no simulator yet, when create runs", ).toEqual([{ state: "making", udid: null }]); - expect( - filesystem.mkdirpModes.get(`${deviceRoot}/sources`), - "under deviceSet simlock the sources set is asked for private to the user", - ).toBe(0o700); expect(runner.calls).toEqual([ { ...listInvocation, options: { timeoutMs: 30_000 } }, { ...seedCreate, options: { timeoutMs: 330_000 } }, @@ -1041,12 +1050,7 @@ describe("IosSimctlDriver", () => { { match: simctl("shutdown", driverData.udid) }, { hangs: true, - match: simctl( - "clone", - driverData.udid, - "simlock-baseline-device-1", - `${deviceRoot}/sources`, - ), + match: simctl("clone", driverData.udid, "simlock-baseline-device-1", sourcesRoot), }, ], }, @@ -1089,7 +1093,7 @@ describe("IosSimctlDriver", () => { }); }); - const coreSimulatorRoot = "/CoreSim"; + const coreSimulatorRoot = "/Users/me/CoreSimulator"; it.each([ { @@ -1099,7 +1103,7 @@ describe("IosSimctlDriver", () => { hung: [ "simctl", "--set", - "/home/.simlock/devices/ios-sources", + xcodeSourcesRoot, "clone", seedUdid, driverData.name, @@ -1133,8 +1137,7 @@ describe("IosSimctlDriver", () => { physical: false, }), deleteArgs: (udid: string) => sourcesSimctl("delete", udid).args, - hung: simctl("clone", driverData.udid, "simlock-baseline-device-1", `${deviceRoot}/sources`) - .args, + hung: simctl("clone", driverData.udid, "simlock-baseline-device-1", sourcesRoot).args, isDefault: false, seeded: false, steps: [ @@ -1481,7 +1484,7 @@ describe("IosSimctlDriver", () => { ...tail, ]); expect(runner.calls.slice(1).map((call) => call.args[2])).toEqual( - runner.calls.slice(1).map(() => `${deviceRoot}/sources`), + runner.calls.slice(1).map(() => sourcesRoot), ); expect(database.prepare("SELECT COUNT(*) AS n FROM ios_source_data").get()).toEqual({ n: 0 }); }, @@ -1729,8 +1732,8 @@ describe("IosSimctlDriver", () => { const orphanUdid = "00000000-0000-0000-0000-0000000000ee"; const filesystem = new MemoryFilesystem(); await plantManagedDevice(filesystem); - await filesystem.mkdirp(`${deviceRoot}/sources/${seedUdid}`); - await filesystem.mkdirp(`${deviceRoot}/sources/${orphanUdid}`); + await filesystem.mkdirp(`${sourcesRoot}/${seedUdid}`); + await filesystem.mkdirp(`${sourcesRoot}/${orphanUdid}`); const database = await seededDatabase(); const runner = new ScriptedProcessRunner([ { match: listInvocation, result: { code: 0, stderr: "", stdout: listFixture } }, @@ -1812,7 +1815,7 @@ describe("IosSimctlDriver", () => { describe("saveSource", () => { const cloneUdid = "00000000-0000-0000-0000-0000000000bb"; const baselineName = "simlock-baseline-device-1"; - const sourcesSet = `${deviceRoot}/sources`; + const sourcesSet = sourcesRoot; const device = { address: driverData.udid, deviceId: driverData.udid, @@ -1831,6 +1834,7 @@ describe("IosSimctlDriver", () => { overridesPath(driverData.udid), overridesPlist({ "a.b": true }), ); + await plantOwnedRoot(filesystem, sourcesSet); await filesystem.mkdirp(`${sourcesSet}/${cloneUdid}/data`); await filesystem.writeFileAtomic(`${sourcesSet}/${cloneUdid}/data/state`, "12345"); await plantLaunchServices(filesystem, `${sourcesSet}/${cloneUdid}`); @@ -5473,7 +5477,7 @@ const recoverFull = { mode: "full", purpose: "recover" } as const; const recoverSlim = { mode: "slim", purpose: "recover" } as const; describe("IosSimctlDriver device set", () => { - const coreSimulatorRoot = "/CoreSim"; + const coreSimulatorRoot = "/Users/me/CoreSimulator"; const runtimeImage = { build: "23E244", identifier: "IMG-26.4-23E244", @@ -5498,14 +5502,14 @@ describe("IosSimctlDriver device set", () => { } it.each([ - ["unset", {}, deviceRoot, true, `${deviceRoot}/sources`, false], - ["simlock", { deviceSet: "simlock" }, deviceRoot, true, `${deviceRoot}/sources`, false], + ["unset", {}, deviceRoot, true, sourcesRoot, false], + ["simlock", { deviceSet: "simlock" }, deviceRoot, true, sourcesRoot, false], [ "default", { deviceSet: "default" }, `${coreSimulatorRoot}/Devices`, false, - "/home/.simlock/devices/ios-sources", + xcodeSourcesRoot, true, ], ] as const)( @@ -5590,7 +5594,7 @@ describe("IosSimctlDriver device set", () => { ).resolves.toBeDefined(); await driver.provision(spec); await expect(filesystem.exists(`${sourcesSet}/${OWNED_ROOT_MARKER_FILE}`)).resolves.toBe( - !scoped, + true, ); await driver.makeReady(device, prepareFull); await driver.destroy(device); @@ -5922,7 +5926,7 @@ describe("IosSimctlDriver device set", () => { [ "simctl", "--set", - scoped ? `${deviceRoot}/sources` : "/home/.simlock/devices/ios-sources", + scoped ? sourcesRoot : xcodeSourcesRoot, "clone", seedUdid, driverData.name, diff --git a/src/drivers/ios/index.ts b/src/drivers/ios/index.ts index 258ec9af7..adaff9ca2 100644 --- a/src/drivers/ios/index.ts +++ b/src/drivers/ios/index.ts @@ -84,7 +84,8 @@ import { fillSimctlDevice } from "./simctl-device.js"; import { IosPhysicalHandler } from "./physical.js"; import { createIosDeviceInput } from "./input/index.js"; import { iosRuntimeVersionFromId } from "./runtime-version.js"; -import { IosSourceTable, sourcesSetFor, type ReadySeed, type SourceRow } from "./source-data.js"; +import { IosSourceTable, type ReadySeed, type SourceRow } from "./source-data.js"; +import { sourcesFolderFor } from "./sources-folder.js"; import { createIosScreenCapture } from "./screen-capture.js"; import { defaultIosDeviceRoot, type IosDriverConfig } from "./definition.js"; import { @@ -340,6 +341,7 @@ export class IosSimctlDriver implements Driver { options: IosSimctlDriverOptions, deviceRoot: string, rootOptions: EnsureOwnedRootOptions | undefined, + sourcesSet: string, ) { this.rebootReadyBeforeGrant = rootOptions === undefined; this.#clock = options.clock; @@ -369,7 +371,7 @@ export class IosSimctlDriver implements Driver { this.#afterBoot = this.#afterBootFor(options); this.#slimByDefault = options.slimByDefault === true; this.#sources = new IosSourceTable(options.database); - this.#sourcesSet = sourcesSetFor(options.simlockHome, deviceRoot, rootOptions !== undefined); + this.#sourcesSet = sourcesSet; this.screenCapture = createScreenCaptureFor( options, deviceRoot, @@ -410,7 +412,13 @@ export class IosSimctlDriver implements Driver { const deviceSet = configuredDeviceSet(options); if (deviceSet === "default") { await refuseOwnSetLeftovers(options.filesystem, join(options.simlockHome, "devices", "ios")); - return new IosSimctlDriver(options, xcodeDeviceSetPath(options), undefined); + const devices = xcodeDeviceSetPath(options); + return new IosSimctlDriver( + options, + devices, + undefined, + await sourcesFolderOf(options, devices), + ); } await refuseDefaultSourcesLeftovers( options.filesystem, @@ -434,7 +442,12 @@ export class IosSimctlDriver implements Driver { }; const deviceRoot = await ensureOwnedRoot(rootOptions); - return new IosSimctlDriver(options, deviceRoot, rootOptions); + return new IosSimctlDriver( + options, + deviceRoot, + rootOptions, + await sourcesFolderOf(options, deviceRoot), + ); } get deviceRoot(): string { @@ -1141,10 +1154,6 @@ export class IosSimctlDriver implements Driver { } async #ensureSourcesSet(): Promise { - if (this.#rootOptions !== undefined) { - await this.#filesystem.mkdirp(this.#sourcesSet, { mode: 0o700 }); - return; - } await ensureOwnedRoot({ filesystem: this.#filesystem, idGenerator: this.#idGenerator, @@ -2231,6 +2240,14 @@ function configuredDeviceSet(options: IosSimctlDriverOptions): "simlock" | "defa return "default"; } +function sourcesFolderOf(options: IosSimctlDriverOptions, deviceSet: string): Promise { + return sourcesFolderFor({ + deviceSet, + filesystem: options.filesystem, + simlockHome: options.simlockHome, + }); +} + function xcodeDeviceSetPath(options: IosSimctlDriverOptions): string { return join(options.coreSimulatorRoot ?? ".", "Devices"); } diff --git a/src/drivers/ios/source-data.ts b/src/drivers/ios/source-data.ts index 2c47f4a49..a07726297 100644 --- a/src/drivers/ios/source-data.ts +++ b/src/drivers/ios/source-data.ts @@ -1,4 +1,3 @@ -import { join } from "node:path"; import type { SqliteDatabase, SqliteSchemaOwner } from "../../ports/index.js"; export const iosSourceDataOwner: SqliteSchemaOwner = { @@ -181,7 +180,3 @@ export class IosSourceTable { })); } } - -export function sourcesSetFor(simlockHome: string, deviceRoot: string, owned: boolean): string { - return owned ? join(deviceRoot, "sources") : join(simlockHome, "devices", "ios-sources"); -} diff --git a/src/drivers/ios/sources-folder.ts b/src/drivers/ios/sources-folder.ts new file mode 100644 index 000000000..956e32562 --- /dev/null +++ b/src/drivers/ios/sources-folder.ts @@ -0,0 +1,37 @@ +import { basename, dirname, join } from "node:path"; + +import type { Filesystem } from "../../ports/index.js"; + +const SOURCES_FOLDER_NAME = "src"; + +export interface SourcesFolderOptions { + readonly deviceSet: string; + readonly filesystem: Filesystem; + readonly simlockHome: string; +} + +/** + * why: ADR 0076 §1: a copy's stored paths are patched byte for byte, so the folder the sources live in + * has a real path exactly as long as the device set's: `src` followed by `_` to the needed length. + */ +export async function sourcesFolderFor(options: SourcesFolderOptions): Promise { + const home = await realPathOf(options.filesystem, options.simlockHome); + const deviceSet = await realPathOf(options.filesystem, options.deviceSet); + const base = join(home, "devices", SOURCES_FOLDER_NAME); + return base + "_".repeat(Math.max(0, deviceSet.length - base.length)); +} + +/** why: Xcode's `Devices` folder or the other setting's root may not exist yet; its real path is its nearest existing parent's, joined with the rest. */ +async function realPathOf(filesystem: Filesystem, path: string): Promise { + try { + return await filesystem.realpath(path); + } catch (error: unknown) { + if (!isMissing(error)) throw error; + if (dirname(path) === path) return path; + return join(await realPathOf(filesystem, dirname(path)), basename(path)); + } +} + +function isMissing(error: unknown): boolean { + return typeof error === "object" && error !== null && "code" in error && error.code === "ENOENT"; +} diff --git a/src/drivers/ios/test-slim.ts b/src/drivers/ios/test-slim.ts index d6ecc930d..7ec0aae16 100644 --- a/src/drivers/ios/test-slim.ts +++ b/src/drivers/ios/test-slim.ts @@ -16,7 +16,10 @@ import { memorySourceDatabase } from "./testing.js"; // why: the slim boot's fixtures, shared by the driver's two test files (index.test.ts is at its size limit). -export const deviceRoot = "/Devices"; +export const deviceRoot = "/home/.simlock/devices/dev-ios"; + +/** why: ADR 0076: the sources folder is as long as the device set (30 characters), `src` and four underscores under this home. */ +export const sourcesRoot = "/home/.simlock/devices/src____"; export const instanceId = "instance-1"; diff --git a/src/drivers/ios/testing.ts b/src/drivers/ios/testing.ts index 2d10c733e..f52b04056 100644 --- a/src/drivers/ios/testing.ts +++ b/src/drivers/ios/testing.ts @@ -33,7 +33,7 @@ export function plantSource(database: SqliteDatabase, source: PlantedSource): Sq osVersion: source.osVersion ?? "26.5", runtimeBuild: source.runtimeBuild, runtimeId: source.runtimeId, - setPath: "/Devices/sources", + setPath: "/home/.simlock/devices/src", sourceId, specKey: `${source.deviceTypeId}\u0000${source.runtimeId}`, }); From e145cf184a5bc29c9b6124356946d221b44cf583 Mon Sep 17 00:00:00 2001 From: Szymon Chmal Date: Sun, 15 Nov 2026 15:48:07 +0100 Subject: [PATCH 03/34] test: iOS is refused sources-path-unfit where no sources folder can have the device set's length (#1569) --- src/drivers/ios/index.test.ts | 68 +++++++++++++++++++++++++++++++++++ 1 file changed, 68 insertions(+) diff --git a/src/drivers/ios/index.test.ts b/src/drivers/ios/index.test.ts index 08b4ebf53..a76ef6e16 100644 --- a/src/drivers/ios/index.test.ts +++ b/src/drivers/ios/index.test.ts @@ -5708,6 +5708,74 @@ describe("IosSimctlDriver device set", () => { } }); + it("refuses iOS with sources-path-unfit and one message per cause where no sources folder can have the device set's path length, and starts where one can", async () => { + const xcodeSim = "/Users/al/Library/Developer/CoreSimulator"; + const xcodeDevices = `${xcodeSim}/Devices`; + const longHome = "/Users/al/very-long-folder-name/ssssss"; + const cases = [ + { + name: "default, home under /private (a)", + home: "/private/tmp/h", + config: { deviceSet: "default" }, + message: `Refusing the ios device set: /private/tmp/h is under /private, where iOS stores each path in two spellings, but Xcode's set ${xcodeDevices} is not. Set SIMLOCK_HOME to a folder outside /tmp and /var.`, + }, + { + name: "default, home too long (b)", + home: longHome, + config: { deviceSet: "default" }, + message: `Refusing the ios device set: the sources folder must have a path as long as ${xcodeDevices} (49 characters), but ${longHome}/devices/ leaves 2 characters for its name, fewer than 3. Set SIMLOCK_HOME to a folder whose real path is at most 37 characters.`, + }, + { + name: "simlock, deviceRoot too short (c)", + home: "/home/.simlock", + config: { deviceRoot: "/d" }, + message: + "Refusing the ios device set: the sources folder must have a path as long as drivers.ios.deviceRoot /d (2 characters), but /home/.simlock/devices/ leaves 0 characters for its name, fewer than 3. Remove drivers.ios.deviceRoot, or set it to a path of at least 26 characters that is under /private only when SIMLOCK_HOME is.", + }, + { + name: "simlock, only the root under /private (c)", + home: "/home/.simlock", + config: { deviceRoot: "/private/tmp/simlock-devices" }, + message: + "Refusing the ios device set: the sources folder must have a path as long as drivers.ios.deviceRoot /private/tmp/simlock-devices (28 characters), but only one of /private/tmp/simlock-devices and /home/.simlock is under /private. Remove drivers.ios.deviceRoot, or set it to a path of at least 26 characters that is under /private only when SIMLOCK_HOME is.", + }, + { + name: "default, home that fits", + home: "/Users/al/.simlock", + config: { deviceSet: "default" }, + }, + ] as const; + + for (const entry of cases) { + const filesystem = new MemoryFilesystem(); + await filesystem.mkdirp(entry.home); + const failure = await IosSimctlDriver.create({ + database: await memorySourceDatabase(), + clock: new FakeClock(), + coreSimulatorRoot: xcodeSim, + driverConfig: entry.config, + filesystem, + idGenerator: { generate: () => "device-1" }, + instanceId, + processRunner: new ScriptedProcessRunner([]), + simlockHome: entry.home, + }) + .then(() => undefined) + .catch((error: unknown) => error); + + if ("message" in entry) { + expect(failure, entry.name).toBeInstanceOf(OwnedRootError); + expect(failure, entry.name).toMatchObject({ + message: entry.message, + platform: "ios", + reason: "sources-path-unfit", + }); + } else { + expect(failure, entry.name).toBeUndefined(); + } + } + }); + it.each([ ["Default", { deviceSet: "Default" }, "Default", 'but it is "Default"'], ["the empty string", { deviceSet: "" }, "", 'but it is ""'], From 1da3680f19219abbe734bb83db6824dd7dd23667 Mon Sep 17 00:00:00 2001 From: Szymon Chmal Date: Sun, 15 Nov 2026 15:50:45 +0100 Subject: [PATCH 04/34] feat(ios): iOS is refused sources-path-unfit where the sources folder cannot have the device set's length (#1569) --- src/core/device-root.ts | 3 +- src/drivers/ios/boot-courtesies.test.ts | 3 ++ src/drivers/ios/devicectl-passthrough.test.ts | 2 +- src/drivers/ios/index.ts | 14 ++++- src/drivers/ios/physical.test.ts | 2 +- src/drivers/ios/sources-folder.ts | 51 +++++++++++++++++++ 6 files changed, 70 insertions(+), 5 deletions(-) diff --git a/src/core/device-root.ts b/src/core/device-root.ts index 71dd585aa..b5156d66d 100644 --- a/src/core/device-root.ts +++ b/src/core/device-root.ts @@ -18,7 +18,8 @@ export type RootRejectionReason = | "non-empty-unowned-root" | "unreadable" | "invalid-device-set" - | "device-set-changed"; + | "device-set-changed" + | "sources-path-unfit"; export interface OwnedRootMarker { readonly schemaVersion: 1; diff --git a/src/drivers/ios/boot-courtesies.test.ts b/src/drivers/ios/boot-courtesies.test.ts index 6189d12b0..e326fff4e 100644 --- a/src/drivers/ios/boot-courtesies.test.ts +++ b/src/drivers/ios/boot-courtesies.test.ts @@ -76,6 +76,7 @@ describe("IosSimctlDriver ios.simulator.headless refusal", () => { }); describe("IosSimctlDriver simulator window", () => { + const coreSimulatorRoot = "/Users/me/CoreSimulator"; const udid = driverData.udid; const slimData = { ...driverData, runtimeId: "com.apple.CoreSimulator.SimRuntime.iOS-18-5" }; const xcrun = (...args: string[]) => ({ command: "xcrun", args: ["simctl", ...args] }); @@ -140,6 +141,7 @@ describe("IosSimctlDriver simulator window", () => { })), ); const driver = await IosSimctlDriver.create({ + coreSimulatorRoot, clock: new FakeClock(), database: await memorySourceDatabase(), driverConfig: { deviceSet: "default" }, @@ -216,6 +218,7 @@ describe("IosSimctlDriver simulator window", () => { const failures: WindowFailedFact[] = []; const driver = await IosSimctlDriver.create({ clock, + coreSimulatorRoot, database: await memorySourceDatabase(), driverConfig: { deviceSet: "default" }, filesystem: new MemoryFilesystem(), diff --git a/src/drivers/ios/devicectl-passthrough.test.ts b/src/drivers/ios/devicectl-passthrough.test.ts index 879cacb95..697c1d02b 100644 --- a/src/drivers/ios/devicectl-passthrough.test.ts +++ b/src/drivers/ios/devicectl-passthrough.test.ts @@ -5,7 +5,7 @@ import { FakeClock, MemoryFilesystem, ScriptedProcessRunner } from "../../ports/ import { IosSimctlDriver } from "./index.js"; import { memorySourceDatabase } from "./testing.js"; -const deviceRoot = "/Devices"; +const deviceRoot = "/home/.simlock/devices/dev-ios"; const UDID = "00008110-001A2B3C4D5E"; const APP = "com.example.app"; const BUILD = "/builds/App.app"; diff --git a/src/drivers/ios/index.ts b/src/drivers/ios/index.ts index adaff9ca2..7ed7ec104 100644 --- a/src/drivers/ios/index.ts +++ b/src/drivers/ios/index.ts @@ -446,7 +446,7 @@ export class IosSimctlDriver implements Driver { options, deviceRoot, rootOptions, - await sourcesFolderOf(options, deviceRoot), + await sourcesFolderOf(options, deviceRoot, configuredRoot(options)), ); } @@ -2240,8 +2240,18 @@ function configuredDeviceSet(options: IosSimctlDriverOptions): "simlock" | "defa return "default"; } -function sourcesFolderOf(options: IosSimctlDriverOptions, deviceSet: string): Promise { +function configuredRoot(options: IosSimctlDriverOptions): string | undefined { + const configured = options.driverConfig["deviceRoot"]; + return typeof configured === "string" ? configured : undefined; +} + +function sourcesFolderOf( + options: IosSimctlDriverOptions, + deviceSet: string, + configuredRoot?: string, +): Promise { return sourcesFolderFor({ + ...(configuredRoot === undefined ? {} : { configuredRoot }), deviceSet, filesystem: options.filesystem, simlockHome: options.simlockHome, diff --git a/src/drivers/ios/physical.test.ts b/src/drivers/ios/physical.test.ts index fbfaaf9b1..471e31898 100644 --- a/src/drivers/ios/physical.test.ts +++ b/src/drivers/ios/physical.test.ts @@ -40,7 +40,7 @@ const simctlListFixture = readFileSync( const SIMLOCK_HOME = "/home/.simlock"; const JSON_DIR = `${SIMLOCK_HOME}/devicectl`; -const DEVICE_ROOT = "/Devices"; +const DEVICE_ROOT = "/home/.simlock/devices/dev-ios"; const READ_LIMIT_MS = 30_000; const UNINSTALL_LIMIT_MS = 60_000; diff --git a/src/drivers/ios/sources-folder.ts b/src/drivers/ios/sources-folder.ts index 956e32562..9299a5b30 100644 --- a/src/drivers/ios/sources-folder.ts +++ b/src/drivers/ios/sources-folder.ts @@ -1,10 +1,13 @@ import { basename, dirname, join } from "node:path"; +import { OwnedRootError } from "../../core/index.js"; import type { Filesystem } from "../../ports/index.js"; const SOURCES_FOLDER_NAME = "src"; export interface SourcesFolderOptions { + /** why: set only for `simlock` with a configured `deviceRoot`: the refusal names that key, where under `default` it names Xcode's set. */ + readonly configuredRoot?: string; readonly deviceSet: string; readonly filesystem: Filesystem; readonly simlockHome: string; @@ -18,9 +21,57 @@ export async function sourcesFolderFor(options: SourcesFolderOptions): Promise= SOURCES_FOLDER_NAME.length; + + if (options.configuredRoot === undefined) { + if (isUnderPrivate(home) && !isUnderPrivate(deviceSet)) { + throw unfit( + deviceSet, + `${home} is under /private, where iOS stores each path in two spellings, but Xcode's set ${deviceSet} is not. Set SIMLOCK_HOME to a folder outside /tmp and /var.`, + ); + } + if (!fitsLength) { + throw unfit( + deviceSet, + `the sources folder must have a path as long as ${deviceSet} (${length} characters), but ${tooShort}. Set SIMLOCK_HOME to a folder whose real path is at most ${String(deviceSet.length - 12)} characters.`, + ); + } + return; + } + + const split = isUnderPrivate(home) !== isUnderPrivate(deviceSet); + if (split || !fitsLength) { + const cause = split + ? `only one of ${options.configuredRoot} and ${home} is under /private` + : tooShort; + throw unfit( + deviceSet, + `the sources folder must have a path as long as drivers.ios.deviceRoot ${options.configuredRoot} (${length} characters), but ${cause}. Remove drivers.ios.deviceRoot, or set it to a path of at least ${String(home.length + 12)} characters that is under /private only when SIMLOCK_HOME is.`, + ); + } +} + +function unfit(deviceSet: string, explanation: string): OwnedRootError { + return new OwnedRootError( + `Refusing the ios device set: ${explanation}`, + "sources-path-unfit", + deviceSet, + "ios", + ); +} + +function isUnderPrivate(path: string): boolean { + return path === "/private" || path.startsWith("/private/"); +} + /** why: Xcode's `Devices` folder or the other setting's root may not exist yet; its real path is its nearest existing parent's, joined with the rest. */ async function realPathOf(filesystem: Filesystem, path: string): Promise { try { From 607f90ec2f7f64f24299a569f7f8e599c28db853 Mon Sep 17 00:00:00 2001 From: Szymon Chmal Date: Sun, 15 Nov 2026 15:51:39 +0100 Subject: [PATCH 05/34] test: a seed or a leftover row naming another set is deleted there and the seed made again in the sources folder (#1569) --- src/drivers/ios/index.test.ts | 44 +++++++++++++++++++++++++++++------ src/drivers/ios/testing.ts | 3 ++- 2 files changed, 39 insertions(+), 8 deletions(-) diff --git a/src/drivers/ios/index.test.ts b/src/drivers/ios/index.test.ts index a76ef6e16..9d7015c97 100644 --- a/src/drivers/ios/index.test.ts +++ b/src/drivers/ios/index.test.ts @@ -205,6 +205,14 @@ interface Catalog { runtimes: { buildversion?: string; identifier: string }[]; } +/** why: a seed of an earlier release is deleted in the set its row names, which is not always today's sources folder. */ +function simctlIn( + set: string, + ...args: readonly string[] +): { readonly command: string; readonly args: string[] } { + return { args: ["simctl", "--set", set, ...args], command: "xcrun" }; +} + /** why: A seed lives in the sources set, a sibling of the lease device set, and its calls are scoped to that. */ function sourcesSimctl(...args: readonly string[]): { readonly command: string; @@ -215,7 +223,7 @@ function sourcesSimctl(...args: readonly string[]): { /** why: A database that already holds the seed of the kind `spec` names, so a test of the copy step starts at the clone. */ async function seededDatabase( - seed: { readonly runtimeBuild?: string; readonly udid?: string } = {}, + seed: { readonly runtimeBuild?: string; readonly setPath?: string; readonly udid?: string } = {}, ): Promise { return plantReadySeed(await memorySourceDatabase(), { deviceTypeId: driverData.deviceTypeId, @@ -1552,9 +1560,23 @@ describe("IosSimctlDriver", () => { runtimeBuild: undefined, remade: false, }, + { + name: "its row names the old sources folder of the simlock set", + seedBuild: "23F79", + runtimeBuild: "23F79", + remade: true, + setPath: `${deviceRoot}/sources`, + }, + { + name: "its row names the old sources folder of the default set", + seedBuild: "23F79", + runtimeBuild: "23F79", + remade: true, + setPath: "/home/.simlock/devices/ios-sources", + }, ])( "makes the seed again before copying it only when it is stale: $name -> remade $remade", - async ({ seedBuild, runtimeBuild, remade }) => { + async ({ seedBuild, runtimeBuild, remade, setPath = sourcesRoot }) => { const staleUdid = "00000000-0000-0000-0000-0000000000bb"; const catalog = JSON.parse(listFixture) as { runtimes: { buildversion?: string; identifier: string }[]; @@ -1570,8 +1592,8 @@ describe("IosSimctlDriver", () => { { match: listInvocation, result: { code: 0, stderr: "", stdout: JSON.stringify(catalog) } }, ...(remade ? [ - { match: sourcesSimctl("shutdown", staleUdid) }, - { match: sourcesSimctl("delete", staleUdid) }, + { match: simctlIn(setPath, "shutdown", staleUdid) }, + { match: simctlIn(setPath, "delete", staleUdid) }, { match: sourcesSimctl( "create", @@ -1599,6 +1621,7 @@ describe("IosSimctlDriver", () => { new FakeClock(), filesystem, await seededDatabase({ + setPath, udid: planted, ...(seedBuild === undefined ? {} : { runtimeBuild: seedBuild }), }), @@ -1691,13 +1714,20 @@ describe("IosSimctlDriver", () => { ) as [string, string, string]; const database = await memorySourceDatabase(); const kind = { deviceTypeId: driverData.deviceTypeId, runtimeId: driverData.runtimeId }; - plantSource(database, { ...kind, maker: "earlier-process", state: "making", udid: gone }); + const oldSet = `${deviceRoot}/sources`; + plantSource(database, { + ...kind, + maker: "earlier-process", + setPath: oldSet, + state: "making", + udid: gone, + }); plantSource(database, { ...kind, maker: "earlier-process", state: "making" }); plantSource(database, { ...kind, maker: "earlier-process", state: "making", udid: stuck }); plantSource(database, { ...kind, udid: ready }); const runner = new ScriptedProcessRunner([ - { match: sourcesSimctl("shutdown", gone) }, - { match: sourcesSimctl("delete", gone) }, + { match: simctlIn(oldSet, "shutdown", gone) }, + { match: simctlIn(oldSet, "delete", gone) }, { match: sourcesSimctl("shutdown", stuck) }, { match: sourcesSimctl("delete", stuck), result: { code: 1, stderr: "busy", stdout: "" } }, { match: listInvocation, result: { code: 0, stderr: "", stdout: listFixture } }, diff --git a/src/drivers/ios/testing.ts b/src/drivers/ios/testing.ts index f52b04056..025ce7256 100644 --- a/src/drivers/ios/testing.ts +++ b/src/drivers/ios/testing.ts @@ -15,6 +15,7 @@ export interface PlantedSource { readonly osVersion?: string; readonly runtimeBuild?: string; readonly runtimeId: string; + readonly setPath?: string; readonly sizeBytes?: number; readonly state?: "making" | "ready"; readonly udid?: string; @@ -33,7 +34,7 @@ export function plantSource(database: SqliteDatabase, source: PlantedSource): Sq osVersion: source.osVersion ?? "26.5", runtimeBuild: source.runtimeBuild, runtimeId: source.runtimeId, - setPath: "/home/.simlock/devices/src", + setPath: source.setPath ?? "/home/.simlock/devices/src____", sourceId, specKey: `${source.deviceTypeId}\u0000${source.runtimeId}`, }); From 8dbedb40dc91b48d09a9d2ede5ab9aac3b69b914 Mon Sep 17 00:00:00 2001 From: Szymon Chmal Date: Sun, 15 Nov 2026 15:52:38 +0100 Subject: [PATCH 06/34] feat(ios): a seed in another set is deleted there and made again in the sources folder (#1569) --- src/drivers/ios/index.test.ts | 13 ++++++++++--- src/drivers/ios/index.ts | 30 ++++++++++++++++-------------- src/drivers/ios/source-data.ts | 8 ++++++-- 3 files changed, 32 insertions(+), 19 deletions(-) diff --git a/src/drivers/ios/index.test.ts b/src/drivers/ios/index.test.ts index 9d7015c97..2504ca1ed 100644 --- a/src/drivers/ios/index.test.ts +++ b/src/drivers/ios/index.test.ts @@ -182,7 +182,12 @@ afterEach(() => { if (call.command !== "xcrun" || call.args[0] !== "simctl") continue; if (UNSCOPED_LEGACY_CALLS.has(call.args.join(" "))) continue; expect(call.args.slice(0, 2)).toEqual(["simctl", "--set"]); - expect([deviceRoot, sourcesRoot]).toContain(call.args[2]); + expect([ + deviceRoot, + sourcesRoot, + `${deviceRoot}/sources`, + "/home/.simlock/devices/ios-sources", + ]).toContain(call.args[2]); } }); @@ -1202,7 +1207,9 @@ describe("IosSimctlDriver", () => { await plantManagedDevice(filesystem); const clock = new FakeClock(); const driver = await IosSimctlDriver.create({ - database: seeded ? await seededDatabase() : await memorySourceDatabase(), + database: seeded + ? await seededDatabase({ setPath: isDefault ? xcodeSourcesRoot : sourcesRoot }) + : await memorySourceDatabase(), clock, ...(isDefault ? { coreSimulatorRoot } : {}), driverConfig: isDefault ? { deviceSet: "default" } : { deviceRoot }, @@ -6007,7 +6014,7 @@ describe("IosSimctlDriver device set", () => { if (scoped) await plantManagedDevice(filesystem); else await filesystem.mkdirp(`${devicesDir}/${driverData.udid}/data`); const driver = await IosSimctlDriver.create({ - database: await seededDatabase(), + database: await seededDatabase({ setPath: scoped ? sourcesRoot : xcodeSourcesRoot }), clock: new FakeClock(), coreSimulatorRoot, driverConfig: config, diff --git a/src/drivers/ios/index.ts b/src/drivers/ios/index.ts index 7ed7ec104..fa1099f3e 100644 --- a/src/drivers/ios/index.ts +++ b/src/drivers/ios/index.ts @@ -633,7 +633,7 @@ export class IosSimctlDriver implements Driver { if (row.kind !== "seed" || row.runtimeId !== runtimeId || row.udid === undefined) continue; const udid = row.udid; try { - await this.#deleteSeedInTurn(udid); + await this.#deleteSeedInTurn(udid, row.setPath); this.#sources.deleteRow(row.sourceId); } catch (error: unknown) { this.#logger?.warn( @@ -899,12 +899,12 @@ export class IosSimctlDriver implements Driver { if (!(await this.#isOrphanSource(sourceId))) { throw new DriverCrashError(`iOS keeps no source ${sourceId}`); } - await this.#deleteSeedInTurn(sourceId); + await this.#deleteSeedInTurn(sourceId, this.#sourcesSet); return; } if (row.udid !== undefined) { const udid = row.udid; - await this.#deleteSeedInTurn(udid); + await this.#deleteSeedInTurn(udid, row.setPath); } this.#sources.deleteRow(sourceId); } @@ -1010,13 +1010,13 @@ export class IosSimctlDriver implements Driver { return made; } - async #deleteSeedInTurn(udid: string): Promise { - await this.#seedTurns.takeToDelete(udid, () => this.#deleteSeedSimulator(udid)); + async #deleteSeedInTurn(udid: string, setPath: string): Promise { + await this.#seedTurns.takeToDelete(udid, () => this.#deleteSeedSimulator(udid, setPath)); } async #findOrMakeSeed(resolved: ResolvedIosSpec, specKey: string): Promise { const seed = this.#sources.findReadySeed(specKey); - if (seed !== undefined && !seedIsStale(seed, resolved)) return seed; + if (seed !== undefined && !seedIsStale(seed, resolved, this.#sourcesSet)) return seed; if (seed !== undefined) await this.#destroySeed(seed); return this.#makeSeed(resolved, specKey); } @@ -1072,7 +1072,7 @@ export class IosSimctlDriver implements Driver { throw error; } this.#sources.markReady(sourceId, await this.#sizeOf(udid)); - return { sourceId, udid, runtimeBuild: resolved.runtime.build }; + return { sourceId, setPath: this.#sourcesSet, udid, runtimeBuild: resolved.runtime.build }; } catch (error: unknown) { this.#sources.deleteRow(sourceId); throw error; @@ -1094,7 +1094,7 @@ export class IosSimctlDriver implements Driver { async #removeLeftover(row: SourceRow): Promise { try { - if (row.udid !== undefined) await this.#deleteSeedSimulator(row.udid); + if (row.udid !== undefined) await this.#deleteSeedSimulator(row.udid, row.setPath); this.#sources.deleteRow(row.sourceId); } catch (error: unknown) { this.#logger?.warn( @@ -1140,14 +1140,15 @@ export class IosSimctlDriver implements Driver { } async #destroySeed(seed: ReadySeed): Promise { - await this.#deleteSeedInTurn(seed.udid); + await this.#deleteSeedInTurn(seed.udid, seed.setPath); this.#sources.deleteRow(seed.sourceId); } - async #deleteSeedSimulator(udid: string): Promise { - await this.#bestEffortShutdown(udid, this.#sourcesSet); + /** why: a row made by an earlier release names the set its simulator is in; `simctl --set` of any other set answers "Invalid device" for it. */ + async #deleteSeedSimulator(udid: string, setPath: string = this.#sourcesSet): Promise { + await this.#bestEffortShutdown(udid, setPath); const args = ["delete", udid]; - const outcome = await this.#invokeSimctl(args, COMMAND_TIMEOUT_MS, this.#sourcesSet); + const outcome = await this.#invokeSimctl(args, COMMAND_TIMEOUT_MS, setPath); // why: a seed deleted by hand is already gone, and its row must still be dropped. if (outcome.kind === "finished" && unknownDevice(outcome.result)) return; this.#checked(args, COMMAND_TIMEOUT_MS, outcome); @@ -2682,8 +2683,9 @@ function alreadyBooted(stderr: string): boolean { return /current state:\s*Booted|already booted/i.test(stderr); } -/** why: a seed built on a runtime whose build changed no longer matches it; with no build on either side only the runtime's presence is checked, and a provision always has the runtime. */ -function seedIsStale(seed: ReadySeed, resolved: ResolvedIosSpec): boolean { +/** why: a seed in another set than today's sources folder was made before ADR 0076, and a copy of it cannot be fixed from; a seed built on a runtime whose build changed no longer matches it; with no build on either side only the runtime's presence is checked, and a provision always has the runtime. */ +function seedIsStale(seed: ReadySeed, resolved: ResolvedIosSpec, sourcesSet: string): boolean { + if (seed.setPath !== sourcesSet) return true; const current = resolved.runtime.build; return seed.runtimeBuild !== undefined && current !== undefined && seed.runtimeBuild !== current; } diff --git a/src/drivers/ios/source-data.ts b/src/drivers/ios/source-data.ts index a07726297..2fafffdd5 100644 --- a/src/drivers/ios/source-data.ts +++ b/src/drivers/ios/source-data.ts @@ -49,6 +49,7 @@ export interface NewSourceRow { export interface SourceRow { readonly sourceId: string; + readonly setPath: string; readonly kind: "seed" | "baseline"; readonly udid: string | undefined; readonly deviceTypeId: string; @@ -63,6 +64,7 @@ export interface SourceRow { export interface ReadySeed { readonly sourceId: string; + readonly setPath: string; readonly udid: string; readonly runtimeBuild: string | undefined; } @@ -116,12 +118,13 @@ export class IosSourceTable { findReadySeed(specKey: string): ReadySeed | undefined { const row = this.#database .prepare( - "SELECT source_id, udid, runtime_build FROM ios_source_data WHERE kind = 'seed' AND state = 'ready' AND spec_key = ?", + "SELECT source_id, set_path, udid, runtime_build FROM ios_source_data WHERE kind = 'seed' AND state = 'ready' AND spec_key = ?", ) .get(specKey); if (row === undefined) return undefined; return { sourceId: row["source_id"] as string, + setPath: row["set_path"] as string, udid: row["udid"] as string, runtimeBuild: (row["runtime_build"] as string | null) ?? undefined, }; @@ -161,12 +164,13 @@ export class IosSourceTable { #rows(where: string, parameters: readonly (string | number)[]): readonly SourceRow[] { return this.#database .prepare( - `SELECT source_id, kind, udid, device_type_id, runtime_id, runtime_build, model, os_version, + `SELECT source_id, set_path, kind, udid, device_type_id, runtime_id, runtime_build, model, os_version, state, maker, size_bytes FROM ios_source_data ${where}`, ) .all(...parameters) .map((row) => ({ sourceId: row["source_id"] as string, + setPath: row["set_path"] as string, kind: row["kind"] as "seed" | "baseline", udid: (row["udid"] as string | null) ?? undefined, deviceTypeId: row["device_type_id"] as string, From 4818a311c56b55ac27a5458daff2d15dd36e2f84 Mon Sep 17 00:00:00 2001 From: Szymon Chmal Date: Sun, 15 Nov 2026 15:53:51 +0100 Subject: [PATCH 07/34] test: converge stores a baseline's stale reason at startup (#1569) --- src/core/create-core.test.ts | 48 ++++++++++++++++++++++++++++++++++++ 1 file changed, 48 insertions(+) diff --git a/src/core/create-core.test.ts b/src/core/create-core.test.ts index 4263dde33..023828080 100644 --- a/src/core/create-core.test.ts +++ b/src/core/create-core.test.ts @@ -425,6 +425,54 @@ describe("createCore", () => { expect(JSON.stringify(sink.records)).toContain("catalog unreadable"); }); + it("converge stores a baseline's stale reason before anything reads it, and logs a check that failed without failing the start", async () => { + const reason = + "saved in /home/.simlock/devices/ios/sources, which copies cannot be fixed from; save it again"; + const cases = [ + { name: "a stale source", failure: undefined, stored: reason, logged: false }, + { + name: "the check's read fails", + failure: new Error("catalog unreadable"), + stored: null, + logged: true, + }, + ]; + + for (const entry of cases) { + const sink = new MemoryLogSink(); + const { core, driver, registry } = await build({ sink }); + testStateOf(registry) + .database.prepare( + `INSERT INTO baselines (name, version, platform, model, os_version, mode, saved_at, source_id) + VALUES ('login', 1, 'ios', 'iPhone 16', '26.5', 'full', '2026-11-03T00:00:00.000Z', 'src-login')`, + ) + .run(); + driver.setSources([ + { + id: "src-login", + kind: "baseline", + model: "iPhone 16", + osVersion: "26.5", + staleReason: reason, + }, + ]); + // why: the startup listing is call 1; the staleness check's read is call 2. + if (entry.failure !== undefined) driver.failOn("listSources", 2, entry.failure); + core.connect(ports()); + + await expect(core.converge(await core.readStartup()), entry.name).resolves.toBeUndefined(); + + expect( + testStateOf(registry).database.prepare("SELECT stale_reason FROM baselines").get(), + entry.name, + ).toEqual({ stale_reason: entry.stored }); + expect( + JSON.stringify(sink.records).includes("could not check baselines at startup"), + entry.name, + ).toBe(entry.logged); + } + }); + it("converge shuts down and deletes a released device whose wipe was deferred, instead of wiping it", async () => { const harness = await build(); const { released } = await releasedLease(harness, { deferReclaim: true }); From 73230b58f37654ae2d8aae76077d9aa56ad68a71 Mon Sep 17 00:00:00 2001 From: Szymon Chmal Date: Sun, 15 Nov 2026 15:54:32 +0100 Subject: [PATCH 08/34] feat(core): an old baseline is stale from the first request after start (#1569) --- src/core/create-core.ts | 18 ++++++++++++++++++ src/drivers/ios/index.test.ts | 31 +++++++++++++++++++++++++++++++ src/drivers/ios/index.ts | 13 ++++++++++--- 3 files changed, 59 insertions(+), 3 deletions(-) diff --git a/src/core/create-core.ts b/src/core/create-core.ts index 78b3ed19e..831fc67f3 100644 --- a/src/core/create-core.ts +++ b/src/core/create-core.ts @@ -444,6 +444,7 @@ export function createCore(options: CoreOptions): Core { await startup.converge(read); await dropReplacedBaselines(); await listStartupSources(options.drivers, options.logger); + await checkBaselinesAtStartup(baselines, options.logger); warmPool.start(); capacityObserver.start(); }, @@ -486,6 +487,23 @@ export function createCore(options: CoreOptions): Core { }; } +/** + * why: a stored stale reason is what a request names a baseline against, so it is stored before the + * first request and the warm pool; a failed check is logged and the start goes on. + */ +async function checkBaselinesAtStartup( + baselines: BaselineService, + logger: Logger | undefined, +): Promise { + try { + await baselines.checkStale(); + } catch (error: unknown) { + logger?.warn( + `could not check baselines at startup: ${error instanceof Error ? error.message : String(error)}`, + ); + } +} + /** * why: the first `listSources` of a process is where a driver sweeps what an earlier process left * in its sources (ADR 0061 §1); a failed read is logged, never fatal, and the sweep runs again on diff --git a/src/drivers/ios/index.test.ts b/src/drivers/ios/index.test.ts index 2504ca1ed..de209ddb6 100644 --- a/src/drivers/ios/index.test.ts +++ b/src/drivers/ios/index.test.ts @@ -1715,6 +1715,37 @@ describe("IosSimctlDriver", () => { }, ); + it("lists a baseline saved in another set as stale with the reason to save it again, one in the sources folder as fresh, and destroys the old one in its own set", async () => { + const [old, fresh] = [ + "00000000-0000-0000-0000-0000000002a0", + "00000000-0000-0000-0000-0000000002b0", + ] as [string, string]; + const oldSet = "/home/.simlock/devices/ios-sources"; + const kind = { deviceTypeId: driverData.deviceTypeId, runtimeId: driverData.runtimeId }; + const database = await memorySourceDatabase(); + plantSource(database, { ...kind, kind: "baseline", setPath: oldSet, udid: old }); + plantSource(database, { ...kind, kind: "baseline", setPath: sourcesRoot, udid: fresh }); + const runner = new ScriptedProcessRunner([ + { match: listInvocation, result: { code: 0, stderr: "", stdout: listFixture } }, + { match: simctlIn(oldSet, "shutdown", old) }, + { match: simctlIn(oldSet, "delete", old) }, + ]); + const driver = await createDriver(runner, new FakeClock(), undefined, database); + + const listed = await driver.listSources(); + + expect(listed.map((source) => source.staleReason)).toEqual([ + `saved in ${oldSet}, which copies cannot be fixed from; save it again`, + undefined, + ]); + const oldId = listed[0]?.id ?? ""; + await driver.destroySource(oldId); + expect(runner.calls.slice(1).map((call) => [call.args[2], call.args[3]])).toEqual([ + [oldSet, "shutdown"], + [oldSet, "delete"], + ]); + }); + it("the first listSources of a process deletes another process's making rows and their simulators, keeps a row whose delete failed, and does not sweep again", async () => { const [gone, stuck, ready] = [1, 2, 3].map( (n) => `00000000-0000-0000-0000-0000000001${String(n)}0`, diff --git a/src/drivers/ios/index.ts b/src/drivers/ios/index.ts index fa1099f3e..167c01e61 100644 --- a/src/drivers/ios/index.ts +++ b/src/drivers/ios/index.ts @@ -829,7 +829,7 @@ export class IosSimctlDriver implements Driver { const catalog = await this.#loadCatalog(); return [ ...rows.map((row) => { - const staleReason = sourceStaleReason(row, catalog); + const staleReason = sourceStaleReason(row, catalog, this.#sourcesSet); return { id: row.sourceId, kind: row.kind, @@ -993,7 +993,7 @@ export class IosSimctlDriver implements Driver { if (row?.state !== "ready" || row.udid === undefined) { throw new DriverCrashError(`iOS keeps no ready source ${sourceId}`); } - const reason = sourceStaleReason(row, await this.#loadCatalog()); + const reason = sourceStaleReason(row, await this.#loadCatalog(), this.#sourcesSet); if (reason !== undefined) throw new DriverCrashError(`source ${sourceId} is stale: ${reason}`); return { udid: row.udid }; } @@ -2691,7 +2691,14 @@ function seedIsStale(seed: ReadySeed, resolved: ResolvedIosSpec, sourcesSet: str } /** why: the phrase reads after "is stale:" in `doctor`, and is what a person acts on, so it names the runtime or device type by id. */ -function sourceStaleReason(row: SourceRow, catalog: SimctlCatalog): string | undefined { +function sourceStaleReason( + row: SourceRow, + catalog: SimctlCatalog, + sourcesSet: string, +): string | undefined { + if (row.setPath !== sourcesSet) { + return `saved in ${row.setPath}, which copies cannot be fixed from; save it again`; + } const runtime = catalog.runtimes.find((entry) => entry.identifier === row.runtimeId); if (runtime === undefined) return `runtime ${row.runtimeId} is not installed`; if ( From adc6b75821edc4efd835f4d05b6bd47f63728527 Mon Sep 17 00:00:00 2001 From: Szymon Chmal Date: Sun, 15 Nov 2026 15:55:08 +0100 Subject: [PATCH 09/34] test: switching deviceSet with sources left in either setting's sources folder is refused (#1569) --- src/drivers/ios/index.test.ts | 28 ++++++++++++++++++++++++++-- 1 file changed, 26 insertions(+), 2 deletions(-) diff --git a/src/drivers/ios/index.test.ts b/src/drivers/ios/index.test.ts index de209ddb6..a2ddca9c2 100644 --- a/src/drivers/ios/index.test.ts +++ b/src/drivers/ios/index.test.ts @@ -5908,7 +5908,7 @@ describe("IosSimctlDriver device set", () => { await fs.writeFileAtomic(`${ownRoot}/${OWNED_ROOT_MARKER_FILE}`, "{}"); }, { - message: `Refusing the ios device set: Simlock's own set at ${ownRoot} still holds 2 simulator(s) (${first}, ${second}). Set drivers.ios.deviceSet back to simlock, run \`simlock nuke --delete-devices\` and \`simlock doctor --purge-orphans\`, then switch again. Delete any that remain with \`xcrun simctl --set ${ownRoot} delete \`, or, for a seed in the sources set, \`xcrun simctl --set ${ownRoot}/sources delete \`.`, + message: `Refusing the ios device set: Simlock's own set at ${ownRoot} still holds 2 simulator(s) (${first}, ${second}). Set drivers.ios.deviceSet back to simlock, run \`simlock nuke --delete-devices\` and \`simlock doctor --purge-orphans\`, then switch again. Delete any that remain with \`xcrun simctl --set ${ownRoot} delete \`.`, path: ownRoot, reason: "device-set-changed", }, @@ -5922,7 +5922,7 @@ describe("IosSimctlDriver device set", () => { await fs.writeFileAtomic(`${ownRoot}/${OWNED_ROOT_MARKER_FILE}`, "{}"); }, { - message: `Refusing the ios device set: Simlock's own set at ${ownRoot} still holds 2 simulator(s) (${first}, ${third}). Set drivers.ios.deviceSet back to simlock, run \`simlock nuke --delete-devices\` and \`simlock doctor --purge-orphans\`, then switch again. Delete any that remain with \`xcrun simctl --set ${ownRoot} delete \`, or, for a seed in the sources set, \`xcrun simctl --set ${ownRoot}/sources delete \`.`, + message: `Refusing the ios device set: Simlock's own set at ${ownRoot} still holds 2 simulator(s) (${first}, ${third}). Set drivers.ios.deviceSet back to simlock, run \`simlock nuke --delete-devices\` and \`simlock doctor --purge-orphans\`, then switch again. Delete any that remain with \`xcrun simctl --set ${ownRoot} delete \`, or, for a seed in a sources folder, \`xcrun simctl --set ${ownRoot}/sources delete \`.`, path: ownRoot, reason: "device-set-changed", }, @@ -5939,6 +5939,30 @@ describe("IosSimctlDriver device set", () => { reason: "device-set-changed", }, ], + [ + "default with a seed in the simlock sources folder", + { deviceSet: "default" }, + async (fs) => { + await fs.mkdirp(`/home/.simlock/devices/src/${third}`); + }, + { + message: `Refusing the ios device set: Simlock's own set at ${ownRoot} still holds 1 simulator(s) (${third}). Set drivers.ios.deviceSet back to simlock, run \`simlock nuke --delete-devices\` and \`simlock doctor --purge-orphans\`, then switch again. Delete any that remain with \`xcrun simctl --set ${ownRoot} delete \`, or, for a seed in a sources folder, \`xcrun simctl --set /home/.simlock/devices/src delete \`.`, + path: ownRoot, + reason: "device-set-changed", + }, + ], + [ + "simlock with a seed in the default sources folder", + { deviceSet: "simlock" }, + async (fs) => { + await fs.mkdirp(`/home/.simlock/devices/src_____/${second}`); + }, + { + message: `Refusing the ios device set: Simlock's sources set at /home/.simlock/devices/src_____ still holds 1 simulator(s) (${second}). Set drivers.ios.deviceSet back to default, run \`simlock nuke --delete-devices\` and \`simlock doctor --purge-orphans\`, then switch again. Delete any that remain with \`xcrun simctl --set /home/.simlock/devices/src_____ delete \`. Run \`simlock nuke --delete-devices\` again afterwards, so Simlock drops its record of them.`, + path: "/home/.simlock/devices/src_____", + reason: "device-set-changed", + }, + ], [ "default with Simlock's set empty", { deviceSet: "default" }, From 1df9f4f98a4934131d569459fb621a9da70d0cde Mon Sep 17 00:00:00 2001 From: Szymon Chmal Date: Sun, 15 Nov 2026 15:55:58 +0100 Subject: [PATCH 10/34] feat(ios): switching deviceSet refuses sources left in either setting's sources folder (#1569) --- src/drivers/ios/device-set-leftovers.ts | 55 ++++++++++++++++--------- src/drivers/ios/index.ts | 27 ++++++++++-- 2 files changed, 58 insertions(+), 24 deletions(-) diff --git a/src/drivers/ios/device-set-leftovers.ts b/src/drivers/ios/device-set-leftovers.ts index 6ec8c4621..81c349987 100644 --- a/src/drivers/ios/device-set-leftovers.ts +++ b/src/drivers/ios/device-set-leftovers.ts @@ -14,39 +14,54 @@ const SWITCH_STEPS = * leave them invisible to the new setting, so the driver refuses to start. The * check reads files only: a start-up `simctl` call would be a new way for start-up to hang. */ -export async function refuseOwnSetLeftovers(filesystem: Filesystem, root: string): Promise { - // why: the sources set of `deviceSet: simlock` is the `sources` folder of the set; its seeds are as invisible to `default` as the set's devices. - const entries = [ - ...(await readFolder(filesystem, root)), - ...(await readFolder(filesystem, join(root, "sources"))), - ]; - const udids = entries.filter((entry) => UDID_PATTERN.test(entry)).sort(); +export async function refuseOwnSetLeftovers( + filesystem: Filesystem, + root: string, + sourcesFolders: readonly string[], +): Promise { + // why: the sources folders `simlock` has used are as invisible to `default` as the set's devices, so seeds in any of them are leftovers. + const inSources = new Map(); + for (const folder of sourcesFolders) { + inSources.set(folder, await udidsIn(filesystem, folder)); + } + const udids = [...(await udidsIn(filesystem, root)), ...[...inSources.values()].flat()].sort(); if (udids.length === 0) return; + const holding = sourcesFolders.filter((folder) => (inSources.get(folder) ?? []).length > 0); + const sourcesNote = + holding.length === 0 + ? "" + : `, or, for a seed in a sources folder, ${holding + .map((folder) => `\`xcrun simctl --set ${folder} delete \``) + .join(" or ")}`; throw new OwnedRootError( - `Refusing the ios device set: Simlock's own set at ${root} still holds ${String(udids.length)} simulator(s) (${udids.join(", ")}). Set drivers.ios.deviceSet back to simlock, ${SWITCH_STEPS} Delete any that remain with \`xcrun simctl --set ${root} delete \`, or, for a seed in the sources set, \`xcrun simctl --set ${join(root, "sources")} delete \`.`, + `Refusing the ios device set: Simlock's own set at ${root} still holds ${String(udids.length)} simulator(s) (${udids.join(", ")}). Set drivers.ios.deviceSet back to simlock, ${SWITCH_STEPS} Delete any that remain with \`xcrun simctl --set ${root} delete \`${sourcesNote}.`, "device-set-changed", root, "ios", ); } -/** why: the sources set of `deviceSet: default` is its own folder, which `simlock` never reads, so seeds left there are refused like devices. */ +/** why: the sources folders of `deviceSet: default` are folders `simlock` never reads, so seeds left in them are refused like devices. */ export async function refuseDefaultSourcesLeftovers( filesystem: Filesystem, - sourcesSet: string, + sourcesFolders: readonly string[], ): Promise { - const udids = (await readFolder(filesystem, sourcesSet)) - .filter((entry) => UDID_PATTERN.test(entry)) - .sort(); - if (udids.length === 0) return; + for (const sourcesSet of sourcesFolders) { + const udids = await udidsIn(filesystem, sourcesSet); + if (udids.length === 0) continue; - throw new OwnedRootError( - `Refusing the ios device set: Simlock's sources set at ${sourcesSet} still holds ${String(udids.length)} simulator(s) (${udids.join(", ")}). Set drivers.ios.deviceSet back to default, ${SWITCH_STEPS} Delete any that remain with \`xcrun simctl --set ${sourcesSet} delete \`. Run \`simlock nuke --delete-devices\` again afterwards, so Simlock drops its record of them.`, - "device-set-changed", - sourcesSet, - "ios", - ); + throw new OwnedRootError( + `Refusing the ios device set: Simlock's sources set at ${sourcesSet} still holds ${String(udids.length)} simulator(s) (${udids.join(", ")}). Set drivers.ios.deviceSet back to default, ${SWITCH_STEPS} Delete any that remain with \`xcrun simctl --set ${sourcesSet} delete \`. Run \`simlock nuke --delete-devices\` again afterwards, so Simlock drops its record of them.`, + "device-set-changed", + sourcesSet, + "ios", + ); + } +} + +async function udidsIn(filesystem: Filesystem, folder: string): Promise { + return (await readFolder(filesystem, folder)).filter((entry) => UDID_PATTERN.test(entry)).sort(); } export async function refuseXcodeSetLeftovers( diff --git a/src/drivers/ios/index.ts b/src/drivers/ios/index.ts index 167c01e61..b17e2db66 100644 --- a/src/drivers/ios/index.ts +++ b/src/drivers/ios/index.ts @@ -411,7 +411,11 @@ export class IosSimctlDriver implements Driver { static async create(options: IosSimctlDriverOptions): Promise { const deviceSet = configuredDeviceSet(options); if (deviceSet === "default") { - await refuseOwnSetLeftovers(options.filesystem, join(options.simlockHome, "devices", "ios")); + const ownRoot = join(options.simlockHome, "devices", "ios"); + await refuseOwnSetLeftovers(options.filesystem, ownRoot, [ + join(ownRoot, "sources"), + ...(await fitSourcesFolder(options, ownRoot)), + ]); const devices = xcodeDeviceSetPath(options); return new IosSimctlDriver( options, @@ -420,10 +424,12 @@ export class IosSimctlDriver implements Driver { await sourcesFolderOf(options, devices), ); } - await refuseDefaultSourcesLeftovers( - options.filesystem, + await refuseDefaultSourcesLeftovers(options.filesystem, [ join(options.simlockHome, "devices", "ios-sources"), - ); + ...(options.coreSimulatorRoot === undefined + ? [] + : await fitSourcesFolder(options, xcodeDeviceSetPath(options))), + ]); if (options.coreSimulatorRoot !== undefined) { await refuseXcodeSetLeftovers( options.filesystem, @@ -2241,6 +2247,19 @@ function configuredDeviceSet(options: IosSimctlDriverOptions): "simlock" | "defa return "default"; } +/** why: the other setting's sources folder only matters when it can exist: where its length is unfit, nothing was ever made there, and it is read to nothing. */ +async function fitSourcesFolder( + options: IosSimctlDriverOptions, + deviceSet: string, +): Promise { + try { + return [await sourcesFolderOf(options, deviceSet)]; + } catch { + // why: a set that cannot be measured is one the check reads anyway, and reports as unreadable. + return []; + } +} + function configuredRoot(options: IosSimctlDriverOptions): string | undefined { const configured = options.driverConfig["deviceRoot"]; return typeof configured === "string" ? configured : undefined; From 86bb59a25bf2582cb07fc6f3c1c374964b563ead Mon Sep 17 00:00:00 2001 From: Szymon Chmal Date: Sun, 15 Nov 2026 15:57:02 +0100 Subject: [PATCH 11/34] feat(e2e): the slow lane's homes sit under $HOME/.sls and find the sources folder (#1569) --- docs/internal/EVENTS.md | 2 +- e2e/helpers/ios-device-set.ts | 6 ++++++ e2e/helpers/lane-home.ts | 10 ++++++++-- e2e/slow-baseline.test.ts | 15 +++++++++------ e2e/slow-ios-smoke.test.ts | 4 ++-- scripts/slow-e2e.sh | 5 +++-- src/core/AGENTS.md | 2 +- src/drivers/ios/AGENTS.md | 4 ++-- .../src/content/docs/docs/reference/events.mdx | 2 +- .../docs/docs/using-devices/build-and-run.mdx | 1 + .../content/docs/docs/worker/troubleshooting.mdx | 2 +- 11 files changed, 35 insertions(+), 18 deletions(-) diff --git a/docs/internal/EVENTS.md b/docs/internal/EVENTS.md index 9cefb77da..37842c403 100644 --- a/docs/internal/EVENTS.md +++ b/docs/internal/EVENTS.md @@ -160,7 +160,7 @@ left behind (#79), each when there is one. | `memory.pressure-changed` | from, to (`none`, `warming-paused`, `new-devices-paused`), cause (the new step's reading: trigger `level` or `floor`, availablePercent, level on macOS, floorPercent for a floor trigger; absent to `none`) | a worker's memory pressure step changed: once per change, never per reading; no usable reading drops the step at once (ADR 0068 §5) | MemoryPressureTracker | implemented | | `cleanup.executed` | rule name, action, target, reason | cleanup executor committed a proposed action | CleanupExecutor | implemented | | `doctor.reconciled` | drift findings | daemon reconciliation completed | Doctor | implemented | -| `driver.root-rejected` | platform, root path, reason (not-absolute/missing-marker/invalid-marker/wrong-instance/symlink/wrong-owner/wrong-permissions/non-empty-unowned-root/unreadable/invalid-device-set/device-set-changed) | a driver's device root failed ownership validation at startup, or (iOS) `drivers.ios.deviceSet` was not `simlock` or `default`, conflicted with `drivers.ios.deviceRoot` or with `ios.simulator.headless: false`, or was switched with simulators left in the set being given up (ADR 0048; `root` is then the configured value or the set holding them), so that platform's driver did not start | DaemonServer | implemented | +| `driver.root-rejected` | platform, root path, reason (not-absolute/missing-marker/invalid-marker/wrong-instance/symlink/wrong-owner/wrong-permissions/non-empty-unowned-root/unreadable/invalid-device-set/device-set-changed/sources-path-unfit) | a driver's device root failed ownership validation at startup, or (iOS) `drivers.ios.deviceSet` was not `simlock` or `default`, conflicted with `drivers.ios.deviceRoot` or with `ios.simulator.headless: false`, or was switched with simulators left in the set being given up (ADR 0048; `root` is then the configured value or the set holding them), or no iOS sources folder can have the device set's path length (`sources-path-unfit`, ADR 0076; `root` is the device set), so that platform's driver did not start | DaemonServer | implemented | | `driver.adb-server-rejected` | port, reason (occupied/start-failed/invalid-port) | Simlock's own adb server could not be established — the port was occupied by a server it does not own, the server it started never began listening, or the configured port is not usable — so the Android driver did not start | DaemonServer | implemented | ## Fleet (gateway mode) diff --git a/e2e/helpers/ios-device-set.ts b/e2e/helpers/ios-device-set.ts index 3f5b8689b..3e974f095 100644 --- a/e2e/helpers/ios-device-set.ts +++ b/e2e/helpers/ios-device-set.ts @@ -17,6 +17,12 @@ export function iosDeviceSet(home: string): string { return join(home, "devices", "ios"); } +/** why: ADR 0076: the sources folder is `src` and `_` until its path is as long as the device set's. */ +export function iosSourcesFolder(home: string): string { + const base = join(home, "devices", "src"); + return base + "_".repeat(Math.max(0, iosDeviceSet(home).length - base.length)); +} + /** why: a simctl call that never answers would otherwise hold its test until the test's own timeout, which names nothing; the driver gives its own slowest call, the slim readback, the same 120 s. */ const SIMCTL_CALL_TIMEOUT_MS = 120_000; diff --git a/e2e/helpers/lane-home.ts b/e2e/helpers/lane-home.ts index c0001ac7b..2b5456d23 100644 --- a/e2e/helpers/lane-home.ts +++ b/e2e/helpers/lane-home.ts @@ -5,7 +5,13 @@ import { basename, join } from "node:path"; import { DatabaseSync } from "node:sqlite"; import { OWNED_ROOT_MARKER_FILE } from "../../src/core/index.js"; -import { emptyDeviceSet, iosDeviceSet, setDevices, simctlInSet } from "./ios-device-set.js"; +import { + emptyDeviceSet, + iosDeviceSet, + iosSourcesFolder, + setDevices, + simctlInSet, +} from "./ios-device-set.js"; import { removeHome } from "./remove-home.js"; type Row = Record; @@ -185,7 +191,7 @@ function folderOf(seed: KeptSeed): string { */ async function pruneSources(home: string, seeds: readonly KeptSeed[]): Promise { const kept = new Set(seeds.map((seed) => basename(folderOf(seed)))); - const iosSources = join(iosDeviceSet(home), "sources"); + const iosSources = iosSourcesFolder(home); if (existsSync(iosSources)) { for (const device of await setDevices(iosSources)) { if (kept.has(device.udid)) continue; diff --git a/e2e/slow-baseline.test.ts b/e2e/slow-baseline.test.ts index cc75918a8..355c59436 100644 --- a/e2e/slow-baseline.test.ts +++ b/e2e/slow-baseline.test.ts @@ -7,7 +7,12 @@ import { describe, expect, it } from "vitest"; import { IOS } from "./helpers/agent-device-targets.js"; import { withDaemon } from "./helpers/index.js"; import type { TestEnv } from "./helpers/env.js"; -import { iosDeviceSet, setDevices, sweepStaleDeviceSets } from "./helpers/ios-device-set.js"; +import { + iosDeviceSet, + iosSourcesFolder, + setDevices, + sweepStaleDeviceSets, +} from "./helpers/ios-device-set.js"; import { DEVICE_READY_MS } from "./helpers/wait.js"; const ANDROID_HOME = @@ -79,12 +84,10 @@ describe.skipIf(process.platform !== "darwin")( expect(listed).toMatchObject({ name: "slow-ios", version: 1 }); expect(listed?.sizeBytes ?? 0).toBeGreaterThan(0); - // why: the sources set sits beside the device set under a custom root, or under `ios-sources` for the default set. - const sourcesSets = [join(deviceSet, "sources"), join(env.home, "devices", "ios-sources")]; - const sourcesSet = sourcesSets.find((candidate) => existsSync(candidate)); - expect(sourcesSet, "no sources set exists after a save").toBeDefined(); + const sourcesSet = iosSourcesFolder(env.home); + expect(existsSync(sourcesSet), "no sources set exists after a save").toBe(true); // why: the sources set also holds the seed the next device is copied from; the baseline's clone is the one named `simlock-baseline-`. - const inSources = (await setDevices(sourcesSet as string)).filter((device) => + const inSources = (await setDevices(sourcesSet)).filter((device) => device.name.startsWith("simlock-baseline-"), ); expect(inSources).toHaveLength(1); diff --git a/e2e/slow-ios-smoke.test.ts b/e2e/slow-ios-smoke.test.ts index b6d2837ac..cb1e5cb38 100644 --- a/e2e/slow-ios-smoke.test.ts +++ b/e2e/slow-ios-smoke.test.ts @@ -1,11 +1,11 @@ import { execFile } from "node:child_process"; -import { join } from "node:path"; import { promisify } from "node:util"; import { describe, expect, it } from "vitest"; import { IOS, withDaemon } from "./helpers/index.js"; import { iosDeviceSet, + iosSourcesFolder, setDevices, sweepStaleDeviceSets, type SimctlDevice, @@ -295,7 +295,7 @@ describe.skipIf(process.platform !== "darwin")( copies.map((device) => device.udid), "the device set holds the copy only", ).toEqual([secondGrant.device.driverDeviceId]); - const seeds = await setDevices(join(deviceSet, "sources")); + const seeds = await setDevices(iosSourcesFolder(env.home)); expect( seeds.map((seed) => seed.state), "the sources set holds the seed shut down", diff --git a/scripts/slow-e2e.sh b/scripts/slow-e2e.sh index 039146c1c..271dc5573 100755 --- a/scripts/slow-e2e.sh +++ b/scripts/slow-e2e.sh @@ -21,7 +21,7 @@ # # Before a run it sources `.slow-lane.env` from the main checkout's root, if there is one: this # machine's settings, such as SIMLOCK_E2E_AGENT_DEVICE. A run's temporary homes live under -# /tmp/simlock-slow, so `clean` and `stop` find a run's daemons, emulators and simulators by +# $HOME/.sls (SIMLOCK_SLOW_TMP), so `clean` and `stop` find a run's daemons, emulators and simulators by # that path and touch nothing else, except the simulators in Xcode's own device set whose durable # mark names the instance of a home under that path (a daemon run with drivers.ios.deviceSet # "default" keeps them there): `clean` and `stop` delete those too. A run starts by cleaning up @@ -33,7 +33,8 @@ set -eu # why: the three overrides let the script's own tests use a scratch lock and home directory. lock=${SIMLOCK_SLOW_LOCK:-/tmp/simlock-slow-e2e.lock} -lane_tmp=${SIMLOCK_SLOW_TMP:-/tmp/simlock-slow} +# why: ADR 0076: the lane's `deviceSet: default` flows need a home short enough for the sources folder to match Xcode's set in length, which a path under /tmp (really /private/tmp) cannot. +lane_tmp=${SIMLOCK_SLOW_TMP:-$HOME/.sls} min_free=${SIMLOCK_SLOW_MIN_FREE_GIB:-15} # why: the worker lock the daemon takes (ADR 0059); src/slow-e2e.test.ts keeps this default equal to defaultWorkerLockPath. worker_lock=${SIMLOCK_SLOW_WORKER_LOCK:-/tmp/simlock-$(id -u)/worker.lock} diff --git a/src/core/AGENTS.md b/src/core/AGENTS.md index 4f77c216a..c2db1d6d5 100644 --- a/src/core/AGENTS.md +++ b/src/core/AGENTS.md @@ -58,7 +58,7 @@ Baselines (ADR 0061 §4): - One save or remove at a time. A save: leasing's `releaseToSave` ends the lease, then `ReclaimCoordinator.retireSaved` calls `driver.saveSource` under the `reclaim` claim. A driver failure quarantines the device and answers `BASELINE_SAVE_FAILED`. - A replace keeps the leased devices of older versions. An older version is dropped only when no device record and no provision (`hold`) has it; that is checked after a save, on every `device.deleted` and at startup. - `remove` refuses a baseline a lease uses, and destroys each source before its row. `removeAll` (nuke) deletes rows first. -- `checkStale` runs before `list` and `doctor` and after `component.removed`. +- `checkStale` runs once at startup (after the sources are listed, before the warm pool starts), before `list` and `doctor`, and after `component.removed`. ## Known gaps diff --git a/src/drivers/ios/AGENTS.md b/src/drivers/ios/AGENTS.md index 918b27a4a..4f36a2d49 100644 --- a/src/drivers/ios/AGENTS.md +++ b/src/drivers/ios/AGENTS.md @@ -9,7 +9,7 @@ The device set: - Under `drivers.ios.deviceSet: simlock`, never `simctl` without `--set`, except three unscoped calls: `findLegacy`, `destroyLegacy`, and the read-only `simctl list -j devices` of `listComponents`. - Under `default` (ADR 0048) the set is Xcode's own: never `--set`, no owned root, and never act on a device whose durable mark does not name this instance. `listManaged` lists only those, and `findLegacy` answers `undefined`. -- `ios.simulator.headless: false` needs `default`: the `simlock` set has no DeviceHub, so iOS is refused (`invalid-device-set`). Simulators left in the set being given up refuse iOS too (`device-set-changed`); that check reads files only, never `simctl`. +- `ios.simulator.headless: false` needs `default`: the `simlock` set has no DeviceHub, so iOS is refused (`invalid-device-set`). Simulators left in the set being given up, or in either setting's sources folder, refuse iOS too (`device-set-changed`); that check reads files only, never `simctl`. - The erasable mark is written before the durable one, never both at once. Under `default` a failed mark write deletes the new simulator before the error is rethrown. Resolve and boot: @@ -27,7 +27,7 @@ Resolve and boot: 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 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 folder (ADR 0076): `$SIMLOCK_HOME/devices/src` followed by `_` until its real path is as long as the device set's, an owned root under both settings. When none can fit, iOS is refused `sources-path-unfit`. A row naming another set (made before) is a seed made again, or a baseline stale (`BASELINE_STALE`, save it again), deleted in the set it names. It is in no `listManaged` or `simlock simctl list`. - Every clone (a seed's copy, `saveSource`'s own clone, a `provision` with `source`) has its `data/var/db/lsd/com.apple.LaunchServices-*.csstore` deleted before its first boot: it records each app, system apps included, under the original device's folder. A clone whose drop fails is deleted. - 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. diff --git a/website/src/content/docs/docs/reference/events.mdx b/website/src/content/docs/docs/reference/events.mdx index f262e5246..0c375516e 100644 --- a/website/src/content/docs/docs/reference/events.mdx +++ b/website/src/content/docs/docs/reference/events.mdx @@ -196,7 +196,7 @@ as `incompatible` in `simlock --gateway worker list`. | `cleanup.executed` | Cleanup shut down or deleted an idle device. | `ruleName` (`idle-shutdown` or `idle-destroy`), `action` (`shutdown` or `destroy`), `target`, `reason` | Relayed | | `disk.pressure-detected` | Free disk space fell below `diskPressure.freeBytesThreshold`. Once per crossing. | `freeBytes`, `threshold` | Relayed | | `memory.pressure-changed` | A worker's memory pressure step changed, from `none`, `warming-paused` or `new-devices-paused` to another. Once per change, never per reading. See `memoryPressure.*`. | `from`, `to`, `cause` (`trigger` `level` or `floor`, `availablePercent`, `level` on macOS, `floorPercent` for a floor trigger; absent when `to` is `none`) | Relayed | -| `driver.root-rejected` | A platform did not start because of its device folder: the folder failed its ownership check, or (iOS) `drivers.ios.deviceSet` was invalid, conflicted with `ios.simulator.headless: false`, or was switched while simulators were left in the old set. `simlock doctor` says what to fix. Reasons include `invalid-device-set` and `device-set-changed`; `root` is then the configured value or the set that holds the leftovers. | `platform`, `root`, `reason` | Relayed | +| `driver.root-rejected` | A platform did not start because of its device folder: the folder failed its ownership check, or (iOS) `drivers.ios.deviceSet` was invalid, conflicted with `ios.simulator.headless: false`, or was switched while simulators were left in the old set. `simlock doctor` says what to fix. Reasons include `invalid-device-set`, `device-set-changed` and `sources-path-unfit` (the iOS sources folder cannot be given the device set's path length); `root` is then the configured value or the set that holds the leftovers. | `platform`, `root`, `reason` | Relayed | | `driver.adb-server-rejected` | The adb server Simlock runs for its emulators could not start (see `drivers.android.adbServerPort`), so Android did not start. | `port`, `reason` (`occupied`, `start-failed`, `invalid-port`) | Relayed |