From 595c1bdf22ad01f10d49962da3d4c7cb420736a7 Mon Sep 17 00:00:00 2001 From: Szymon Chmal Date: Fri, 20 Nov 2026 08:30:21 +0100 Subject: [PATCH 1/5] fix(ios): a copy skips recorded files its source no longer has (#1790) --- src/drivers/ios/AGENTS.md | 2 +- src/drivers/ios/index-seed-record.test.ts | 29 +++++++++++- src/drivers/ios/index-seed-swap.test.ts | 55 ++++++++++++++++++++-- src/drivers/ios/lineage-files.ts | 56 +++++++++++++++-------- src/drivers/ios/seeds.ts | 2 +- 5 files changed, 119 insertions(+), 25 deletions(-) diff --git a/src/drivers/ios/AGENTS.md b/src/drivers/ios/AGENTS.md index 56475f312..b4f0c64f7 100644 --- a/src/drivers/ios/AGENTS.md +++ b/src/drivers/ios/AGENTS.md @@ -30,7 +30,7 @@ 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-` 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. +- 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 recorded entry missing from the copy is skipped and counted, and any other 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 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. diff --git a/src/drivers/ios/index-seed-record.test.ts b/src/drivers/ios/index-seed-record.test.ts index fe7b8d827..a84673fb4 100644 --- a/src/drivers/ios/index-seed-record.test.ts +++ b/src/drivers/ios/index-seed-record.test.ts @@ -41,10 +41,14 @@ class UnreadableFiles extends MemoryFilesystem { readonly unreadable = new Set(); /** why: CoreSimulator's atomic write lists a `*.sb-*` temp file and renames it away before the walk reaches it. */ readonly vanishing = new Set(); + /** why: the same rename can land just after the walk's lstat, before the file is read. */ + readonly vanishingAfterLstat = new Set(); override async lstat(path: string): ReturnType { if (this.vanishing.has(path)) await this.rm(path); - return super.lstat(path); + const details = await super.lstat(path); + if (this.vanishingAfterLstat.has(path)) await this.rm(path); + return details; } override async openFile(path: string): ReturnType { @@ -125,12 +129,16 @@ async function saveBaseline(options: { readonly lineage?: readonly string[]; readonly plant: (filesystem: UnreadableFiles) => Promise; readonly vanishingPaths?: readonly string[]; + readonly vanishingAfterLstatPaths?: readonly string[]; }): Promise { const database = await memorySourceDatabase(); const filesystem = new UnreadableFiles(); await plantManagedDevice(filesystem); await options.plant(filesystem); for (const path of options.vanishingPaths ?? []) filesystem.vanishing.add(path); + for (const path of options.vanishingAfterLstatPaths ?? []) { + filesystem.vanishingAfterLstat.add(path); + } const opener = new FakeSqliteOpener(filesystem); const logger = new RecordingLogger(); const runner = new ScriptedProcessRunner([ @@ -349,4 +357,23 @@ describe("IosSimctlDriver source records", () => { ]); expect(saved.logger.warnings).toEqual([]); }); + + it("a baseline is saved when a file in its clone is renamed away after the walk reaches it but before it is read, and the file is not recorded", async () => { + const baselineFolder = `${sourcesSet}/${baselineUdid}`; + const lease = driverData.udid.toUpperCase(); + const temp = `${baselineFolder}/device.plist.sb-55c05b11-ISuHtw`; + + const saved = await saveBaseline({ + lineage: [lineageUdid], + plant: async (filesystem) => { + await plantBytes(filesystem, `${baselineFolder}/device.plist`, Buffer.from(lease)); + await plantBytes(filesystem, temp, Buffer.from(lease)); + }, + vanishingAfterLstatPaths: [temp], + }); + + expect(saved.error).toBeUndefined(); + expect(recorded(saved.database)).toEqual([{ kind: "file", relative_path: "device.plist" }]); + expect(saved.logger.warnings).toEqual([]); + }); }); diff --git a/src/drivers/ios/index-seed-swap.test.ts b/src/drivers/ios/index-seed-swap.test.ts index 17bdffc23..87cffada9 100644 --- a/src/drivers/ios/index-seed-swap.test.ts +++ b/src/drivers/ios/index-seed-swap.test.ts @@ -123,7 +123,39 @@ describe("IosSimctlDriver copy swap", () => { ); expect(device.driverData).toMatchObject({ lineage: [lineageUdid] }); expect(logger.debugs).toEqual([ - `swapped 9 files and 1 links in 40 ms for ${copyUdid}; 1 unreadable`, + `swapped 9 files and 1 links in 40 ms for ${copyUdid}; 1 unreadable, 0 missing`, + ]); + }); + + it("a copy whose source recorded a file and a link it no longer has skips them, swaps the rest and logs them as missing", async () => { + const database = await seededDatabase({ + files: [ + { kind: "file", relativePath: "data/gone.plist" }, + { kind: "link", relativePath: "data/GoneLogs" }, + { kind: "file", relativePath: "data/kept.plist" }, + ], + lineage: [lineageUdid], + }); + const runner = new ScriptedProcessRunner([ + { match: listInvocation, result: { code: 0, stderr: "", stdout: listFixture } }, + { + match: sourcesSimctl("clone", seedUdid, driverData.name, deviceRoot), + result: { code: 0, stderr: "", stdout: `${copyUdid}\n` }, + }, + ]); + const filesystem = new MemoryFilesystem(); + const logger = new RecordingLogger(); + await plantManagedDevice(filesystem); + const kept = `${deviceRoot}/${copyUdid}/data/kept.plist`; + await plantBytes(filesystem, kept, Buffer.from(`/Devices/${lineageUdid}/data`)); + const driver = await createDriver(runner, new FakeClock(), filesystem, database, logger); + + await driver.provision(spec); + + expect((await readBytes(filesystem, kept)).toString()).toBe(`/Devices/${copyUdid}/data`); + expect(runner.calls.some((call) => call.args.includes("delete"))).toBe(false); + expect(logger.debugs).toEqual([ + `swapped 1 files and 0 links in 0 ms for ${copyUdid}; 0 unreadable, 2 missing`, ]); }); @@ -133,15 +165,27 @@ describe("IosSimctlDriver copy swap", () => { throw new Error("disk full"); } } + class LockedLinks extends MemoryFilesystem { + override async readlink(path: string): Promise { + throw Object.assign(new Error(`EACCES: permission denied, readlink '${path}'`), { + code: "EACCES", + }); + } + } const file = `${deviceRoot}/${copyUdid}/data/Library/note.plist`; const cases = [ { label: "control: a swap that works", error: undefined }, - { label: "a recorded file gone", gone: true, error: /ENOENT/ }, { label: "a write that fails", filesystem: new FailingWrites(), error: /disk full/, }, + { + label: "a recorded link that cannot be read", + filesystem: new LockedLinks(), + link: true, + error: /EACCES/, + }, { label: "a result of another length", lineage: ["AAAAAAAA-1111-2222-3333-BBBBBBBBBBB"], @@ -151,7 +195,10 @@ describe("IosSimctlDriver copy swap", () => { ]; for (const attempt of cases) { const database = await seededDatabase({ - files: [{ kind: "file", relativePath: "data/Library/note.plist" }], + files: [ + { kind: "file", relativePath: "data/Library/note.plist" }, + ...(attempt.link === true ? [{ kind: "link" as const, relativePath: "data/Logs" }] : []), + ], lineage: attempt.lineage ?? [lineageUdid], }); const runner = new ScriptedProcessRunner([ @@ -166,7 +213,7 @@ describe("IosSimctlDriver copy swap", () => { await plantManagedDevice(filesystem); await plantBytes( filesystem as MemoryFilesystem, - attempt.gone === true ? `${deviceRoot}/${copyUdid}/data/other` : file, + file, Buffer.from(`/Devices/${lineageUdid}/ AAAAAAAA-1111-2222-3333-BBBBBBBBBBB`), ); const driver = await createDriver(runner, new FakeClock(), filesystem, database); diff --git a/src/drivers/ios/lineage-files.ts b/src/drivers/ios/lineage-files.ts index 8a6edb617..c0798fdaa 100644 --- a/src/drivers/ios/lineage-files.ts +++ b/src/drivers/ios/lineage-files.ts @@ -17,42 +17,60 @@ const WAL_SUFFIX = "-wal"; export interface SwapCounts { readonly files: number; readonly links: number; + readonly missing: number; readonly unreadable: number; } -/** why: ADR 0076 §3: before its first boot a copy's recorded files and links name its own UDID in place of the lineage's, each keeping its length; an unreadable file is left. */ +/** why: ADR 0076 §3: before its first boot a copy's recorded files and links name its own UDID in place of the lineage's, each keeping its length; an unreadable file is left, and a missing one has nothing left to swap (#1714). */ export async function swapCopyFiles( filesystem: Filesystem, folder: string, files: readonly SourceFile[], swap: LineageSwap, ): Promise { - const counts = { files: 0, links: 0, unreadable: 0 }; + const counts = { files: 0, links: 0, missing: 0, unreadable: 0 }; for (const file of files) { const path = `${folder}/${file.relativePath}`; if (file.kind === "unreadable") { counts.unreadable += 1; - } else if (file.kind === "link") { - counts.links += 1; - const target = Buffer.from(await filesystem.readlink(path)); - const swapped = swapLineage(target, swap); - checkLength(path, target, swapped); - if (!target.equals(swapped)) { - await filesystem.replaceSymlink(path, Buffer.from(swapped).toString()); - } - } else { - counts.files += 1; - await eachWindow(filesystem, path, async (window, start) => { - const swapped = swapLineage(window, swap); - checkLength(path, window, swapped); - if (!window.equals(swapped)) await filesystem.writeAt(path, start, swapped); - return false; - }); + continue; + } + try { + await swapEntry(filesystem, path, file.kind, swap); + } catch (error: unknown) { + if (!isMissingPathError(error)) throw error; + counts.missing += 1; + continue; } + if (file.kind === "link") counts.links += 1; + else counts.files += 1; } return counts; } +async function swapEntry( + filesystem: Filesystem, + path: string, + kind: "file" | "link", + swap: LineageSwap, +): Promise { + if (kind === "link") { + const target = Buffer.from(await filesystem.readlink(path)); + const swapped = swapLineage(target, swap); + checkLength(path, target, swapped); + if (!target.equals(swapped)) { + await filesystem.replaceSymlink(path, Buffer.from(swapped).toString()); + } + return; + } + await eachWindow(filesystem, path, async (window, start) => { + const swapped = swapLineage(window, swap); + checkLength(path, window, swapped); + if (!window.equals(swapped)) await filesystem.writeAt(path, start, swapped); + return false; + }); +} + function checkLength(path: string, before: Uint8Array, after: Uint8Array): void { if (before.length !== after.length) { throw new DriverCrashError(`swapping UDIDs in ${path} changed its length`); @@ -160,6 +178,8 @@ async function classify( ); return names ? "file" : undefined; } catch (error: unknown) { + // why: a file renamed away after the walk's lstat names nothing a copy could swap (#1714). + if (isMissingPathError(error)) return undefined; options.logger?.warn( `could not read ${path} in source ${options.udid}: ${errorMessage(error)}; recorded as unreadable`, ); diff --git a/src/drivers/ios/seeds.ts b/src/drivers/ios/seeds.ts index 8acf7caf6..8a88cfd39 100644 --- a/src/drivers/ios/seeds.ts +++ b/src/drivers/ios/seeds.ts @@ -522,7 +522,7 @@ export class Seeds { { lineage, own: udid }, ); this.#logger?.debug( - `swapped ${String(counts.files)} files and ${String(counts.links)} links in ${String(this.#clock.now() - started)} ms for ${udid}; ${String(counts.unreadable)} unreadable`, + `swapped ${String(counts.files)} files and ${String(counts.links)} links in ${String(this.#clock.now() - started)} ms for ${udid}; ${String(counts.unreadable)} unreadable, ${String(counts.missing)} missing`, ); } From 2d537bee773044d55d5e94df63d815e4371fda5e Mon Sep 17 00:00:00 2001 From: Szymon Chmal Date: Fri, 20 Nov 2026 08:37:21 +0100 Subject: [PATCH 2/5] fix(ios): keep the iOS manual under its size cap (#1790) --- src/drivers/ios/AGENTS.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/drivers/ios/AGENTS.md b/src/drivers/ios/AGENTS.md index b4f0c64f7..56475f312 100644 --- a/src/drivers/ios/AGENTS.md +++ b/src/drivers/ios/AGENTS.md @@ -30,7 +30,7 @@ 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-` 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 recorded entry missing from the copy is skipped and counted, and any other failed drop or swap deletes it. No lineage: a seed is remade, a baseline stale. +- 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 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. From 6e399577006379877e86b446ccf1153c8254370e Mon Sep 17 00:00:00 2001 From: Szymon Chmal Date: Fri, 20 Nov 2026 08:39:48 +0100 Subject: [PATCH 3/5] docs(ios): the manual says a missing recorded entry is skipped (#1790) --- src/drivers/ios/AGENTS.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/drivers/ios/AGENTS.md b/src/drivers/ios/AGENTS.md index 56475f312..17e09f445 100644 --- a/src/drivers/ios/AGENTS.md +++ b/src/drivers/ios/AGENTS.md @@ -29,8 +29,8 @@ 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 seed is made from a throwaway (ADR 0076): `simlock-seed-` 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. +- A seed is made from a throwaway (ADR 0076): `simlock-seed-` 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. An undeletable log folder 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; a missing entry is skipped. 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 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. From b5b0b743ba012ac91e0992661c76cee93eab9c8f Mon Sep 17 00:00:00 2001 From: Szymon Chmal Date: Fri, 20 Nov 2026 08:39:58 +0100 Subject: [PATCH 4/5] docs(ios): trim the iOS manual under its cap (#1790) --- src/drivers/ios/AGENTS.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/drivers/ios/AGENTS.md b/src/drivers/ios/AGENTS.md index 17e09f445..324cddd91 100644 --- a/src/drivers/ios/AGENTS.md +++ b/src/drivers/ios/AGENTS.md @@ -29,7 +29,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 seed is made from a throwaway (ADR 0076): `simlock-seed-` 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. An undeletable log folder is logged and the make or save goes on; a throwaway that cannot be deleted fails the make. +- A seed is made from a throwaway (ADR 0076): `simlock-seed-` 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. An undeletable log folder is logged and the make or save goes on; an undeletable throwaway 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; a missing entry is skipped. 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 5 silent minutes more kills and logs it. From 0878d3e7b845340d23f6f14b06dda009d1c56e8f Mon Sep 17 00:00:00 2001 From: Szymon Chmal Date: Fri, 20 Nov 2026 08:40:12 +0100 Subject: [PATCH 5/5] docs(ios): trim the iOS manual under its cap (#1790) --- src/drivers/ios/AGENTS.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/drivers/ios/AGENTS.md b/src/drivers/ios/AGENTS.md index 324cddd91..e32c479ca 100644 --- a/src/drivers/ios/AGENTS.md +++ b/src/drivers/ios/AGENTS.md @@ -30,7 +30,7 @@ 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-` 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. An undeletable log folder is logged and the make or save goes on; an undeletable throwaway 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; a missing entry is skipped. No lineage: a seed is remade, a baseline stale. +- 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; a missing one is skipped. 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 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.