Skip to content

Commit 9189275

Browse files
committed
feat(apple): release a speculative runner when the plan is proven observation-only
#2198 requires a `none` runner demand to retain no runner, not only to start none. A runner a prewarm started that no command has used yet is speculative: the session records that mark at creation, the first command that is not a readiness probe clears it, and a Simulator open whose plan is proven observation-only asks the runner owner to release a speculative session in the background, so the observation path never waits for a runner to stop either. A runner that has served a command is the session's working runner and stays under the existing idle-stop policy, so a mixed workload does not pay a cold runner start at every observation-only open. The release goes through the runner provider seam: the local provider stops its own speculative session; a provider that never starts speculative work omits the operation and releases nothing.
1 parent 7616ba2 commit 9189275

17 files changed

Lines changed: 315 additions & 22 deletions

‎.fallowrc.json‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -97,6 +97,7 @@
9797
"exports": [
9898
"detachIosSimulatorRunnerSessionsForShutdown",
9999
"hasLiveIosRunnerSession",
100+
"releaseSpeculativeIosRunnerSessionFor",
100101
"stopAllIosRunnerSessions"
101102
]
102103
},

‎CONTEXT.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -125,7 +125,7 @@ The daemon-side truth for route ownership and request-policy traits.
125125
Per-command classes steering Apple runner lifecycle and recovery, independent of the public surface.
126126

127127
**Runner demand**:
128-
What a local-Simulator open prepares of the XCTest runner for the remaining batch steps.
128+
What a Simulator open prepares, or releases unused, of the XCTest runner for remaining steps.
129129

130130
**Daemon RPC protocol version**:
131131
The integer that detects breaking compatibility across the remote daemon boundary.

‎packages/contracts/src/application-lifecycle-runtime.ts‎

Lines changed: 10 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -77,10 +77,11 @@ export type OpenApplicationPreparationInput = Readonly<{
7777
/**
7878
* How much the platform's interaction host (the XCTest runner on iOS) is known to be needed by
7979
* the plan that contains an open. `none`: every following step is proven observation-only, so this
80-
* open starts no runner (an already-live runner stays under the existing idle-stop policy).
81-
* `possible`: the plan is unknown, so a speculative prewarm may run but observation never awaits
82-
* it. `required`: a following step needs the runner, so readiness is prepared now and awaited by
83-
* that step.
80+
* open starts no runner and releases a speculative one (started by an earlier prewarm, used by no
81+
* command); a runner that has served a command is the session's and stays under the idle-stop
82+
* policy. `possible`: the plan is unknown, so a speculative prewarm may run but observation never
83+
* awaits it. `required`: a following step needs the runner, so readiness is prepared now and
84+
* awaited by that step.
8485
*/
8586
export type OpenApplicationRunnerDemand = 'none' | 'possible' | 'required';
8687

@@ -304,6 +305,11 @@ export type AppleApplicationTools = Readonly<{
304305
device: DeviceInfo,
305306
execution: Readonly<{ requestId?: string }>,
306307
): Promise<boolean>;
308+
/** Stops a runner a prewarm started that no command has used; true when one was stopped. */
309+
releaseSpeculativeRunner(
310+
device: DeviceInfo,
311+
execution: Readonly<{ requestId?: string }>,
312+
): Promise<boolean>;
307313
scheduleRunnerIdleStop(deviceId: string): void;
308314
prepareRunner(
309315
device: DeviceInfo,

‎packages/platform-apple/src/core/runner-client.ts‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -22,6 +22,8 @@ export const notifyIosRunnerAppRelaunched: AppleRunnerClient['notifyIosRunnerApp
2222
client.notifyIosRunnerAppRelaunched;
2323
export const hasLiveIosRunnerSession: AppleRunnerClient['hasLiveIosRunnerSession'] =
2424
client.hasLiveIosRunnerSession;
25+
export const releaseSpeculativeIosRunnerSessionFor: AppleRunnerClient['releaseSpeculativeIosRunnerSessionFor'] =
26+
client.releaseSpeculativeIosRunnerSessionFor;
2527
export const prewarmAppleRunnerCache: AppleRunnerClient['prewarmAppleRunnerCache'] =
2628
client.prewarmAppleRunnerCache;
2729
export const prewarmIosRunnerSession: AppleRunnerClient['prewarmIosRunnerSession'] =

‎packages/platform-apple/src/lifecycle.test.ts‎

Lines changed: 34 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -294,6 +294,10 @@ function simulatorHost(overrides: {
294294
overrides.events.push('reset');
295295
});
296296
const hasLiveRunnerSession = vi.fn(overrides.hasLiveRunnerSession ?? (async () => false));
297+
const releaseSpeculativeRunner = vi.fn(async () => {
298+
overrides.events.push('release');
299+
return true;
300+
});
297301
const host = {
298302
...baseHost,
299303
clock: { ...baseHost.clock, sleep: async () => {} },
@@ -303,14 +307,22 @@ function simulatorHost(overrides: {
303307
prewarmRunnerSession,
304308
notifyRunnerAppRelaunched,
305309
hasLiveRunnerSession,
310+
releaseSpeculativeRunner,
306311
},
307312
} as unknown as PlatformRuntimeHost;
308-
return { host, prewarmRunnerSession, notifyRunnerAppRelaunched, hasLiveRunnerSession };
313+
return {
314+
host,
315+
prewarmRunnerSession,
316+
notifyRunnerAppRelaunched,
317+
hasLiveRunnerSession,
318+
releaseSpeculativeRunner,
319+
};
309320
}
310321

311-
test('a Simulator open whose plan is observation-only starts no runner and reports demand none', async () => {
322+
test('a Simulator open whose plan is observation-only starts no runner, releases a speculative one, and reports demand none', async () => {
312323
const events: string[] = [];
313-
const { host, prewarmRunnerSession, notifyRunnerAppRelaunched } = simulatorHost({ events });
324+
const { host, prewarmRunnerSession, notifyRunnerAppRelaunched, releaseSpeculativeRunner } =
325+
simulatorHost({ events });
314326
const lifecycle = bindAppleApplicationLifecycle({
315327
host,
316328
device: simulator,
@@ -326,7 +338,11 @@ test('a Simulator open whose plan is observation-only starts no runner and repor
326338
expect(outcome.timing.runnerPrewarmScheduled).toBeUndefined();
327339
expect(prewarmRunnerSession).not.toHaveBeenCalled();
328340
expect(notifyRunnerAppRelaunched).not.toHaveBeenCalled();
329-
expect(events).toEqual(['open']);
341+
// The release goes to the runner owner before the app opens and is never awaited by the open.
342+
expect(releaseSpeculativeRunner).toHaveBeenCalledExactlyOnceWith(simulator, {
343+
plannedOperations: ['captureSnapshot', 'findText', 'captureScreenshot'],
344+
});
345+
expect(events).toEqual(['release', 'open']);
330346
});
331347

332348
test.each([
@@ -337,15 +353,16 @@ test.each([
337353
async (_name, plan, expectedDemand) => {
338354
const events: string[] = [];
339355
let releasePrewarm = () => {};
340-
const { host, prewarmRunnerSession, notifyRunnerAppRelaunched } = simulatorHost({
341-
events,
342-
// A prewarm that never finishes inside the open: if the open awaited runner readiness
343-
// this test would time out instead of passing.
344-
prewarmRunnerSession: () =>
345-
new Promise<void>((resolve) => {
346-
releasePrewarm = resolve;
347-
}),
348-
});
356+
const { host, prewarmRunnerSession, notifyRunnerAppRelaunched, releaseSpeculativeRunner } =
357+
simulatorHost({
358+
events,
359+
// A prewarm that never finishes inside the open: if the open awaited runner readiness
360+
// this test would time out instead of passing.
361+
prewarmRunnerSession: () =>
362+
new Promise<void>((resolve) => {
363+
releasePrewarm = resolve;
364+
}),
365+
});
349366
const lifecycle = bindAppleApplicationLifecycle({
350367
host,
351368
device: simulator,
@@ -373,6 +390,8 @@ test.each([
373390
expect(prewarmRunnerSession).toHaveBeenCalledOnce();
374391
// The starting runner has no cached target, so nothing is reset and nothing is awaited.
375392
expect(notifyRunnerAppRelaunched).not.toHaveBeenCalled();
393+
// Only a proven observation-only plan releases; a plan that may need the runner keeps it.
394+
expect(releaseSpeculativeRunner).not.toHaveBeenCalled();
376395
expect(events).toEqual(['open']);
377396
},
378397
);
@@ -459,7 +478,7 @@ test('a Simulator open lets the launched app become observable instead of sleepi
459478

460479
expect(awaitObservable).toHaveBeenCalledWith(simulator, 'com.example.app', signal);
461480
expect(outcome.timing.postOpenObservation).toBe('observable');
462-
expect(events).toEqual(['open', 'observe']);
481+
expect(events).toEqual(['release', 'open', 'observe']);
463482
});
464483

465484
test('a Simulator whose bridge cannot answer keeps the fixed settle', async () => {
@@ -481,7 +500,7 @@ test('a Simulator whose bridge cannot answer keeps the fixed settle', async () =
481500
});
482501

483502
expect(outcome.timing.postOpenObservation).toBe('unobservable');
484-
expect(events).toEqual(['open', 'sleep']);
503+
expect(events).toEqual(['release', 'open', 'sleep']);
485504
});
486505

487506
test('a tvOS Simulator relaunch keeps the awaited prewarm and asks for no observation', async () => {

‎packages/platform-apple/src/lifecycle.ts‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -21,6 +21,7 @@ import {
2121
resolveRunnerPrewarmPolicy,
2222
settleAppleOpen,
2323
type MutableOpenTiming,
24+
releaseSpeculativeRunner,
2425
} from './open-policy.ts';
2526
import type { LaunchObservationPort } from './snapshot-observability.ts';
2627
import { isApplePlatform, isIosFamily, type DeviceInfo } from '@agent-device/kernel/device';
@@ -99,6 +100,7 @@ async function openAppleApplication(
99100
const runner = createRunnerPrewarm(host, binding, input, timing);
100101
const policy = resolveRunnerPrewarmPolicy(binding.device, input, localIosSimulator);
101102
if (policy.runnerDemand) timing.runnerDemand = policy.runnerDemand;
103+
releaseSpeculativeRunner(host, binding, input, policy);
102104
const { shouldPrewarmRunner } = policy;
103105
const retainRunnerForRelaunch = shouldRetainRunnerForRelaunch(
104106
binding.device,

‎packages/platform-apple/src/open-policy.ts‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -50,6 +50,23 @@ export function resolveRunnerPrewarmPolicy(
5050
};
5151
}
5252

53+
/**
54+
* A proven observation-only plan keeps no runner it did not ask for: a speculative one (an earlier
55+
* prewarm no command has used) is released through the runner owner, in the background so the
56+
* observation path never waits for a runner to stop either.
57+
*/
58+
export function releaseSpeculativeRunner(
59+
host: Pick<PlatformRuntimeHost, 'appleApplications'>,
60+
binding: Readonly<{ device: DeviceInfo }>,
61+
input: OpenApplicationInput,
62+
policy: RunnerPrewarmPolicy,
63+
): void {
64+
if (policy.runnerDemand !== 'none') return;
65+
void host.appleApplications
66+
.releaseSpeculativeRunner(binding.device, input.execution)
67+
.catch(() => {});
68+
}
69+
5370
/**
5471
* Lets the opened app become observable before the open returns. A local Simulator asks its AX
5572
* bridge, bounded by the launch-transition windows the bridge itself defines, so the first

‎packages/platform-apple/src/runner-operations-facade.ts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,7 @@ export {
88
prewarmAppleRunnerCache,
99
prewarmIosRunnerSession,
1010
readStaleRunnerLease,
11+
releaseSpeculativeIosRunnerSessionFor,
1112
resolveRunnerAppBundleId,
1213
runAppleRunnerCommand,
1314
scheduleIosRunnerIdleStop,
Lines changed: 180 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,180 @@
1+
import assert from 'node:assert/strict';
2+
import { beforeEach, test, vi } from 'vitest';
3+
import { IOS_SIMULATOR } from './device-fixtures.ts';
4+
import { appleRunnerTestHost } from '../test-host.ts';
5+
import {
6+
makeBackgroundRunner,
7+
makeClassifyOwnerLivenessViaMocks,
8+
runnerResponse,
9+
} from './runner-session-fixtures.ts';
10+
import { mkdtempForTestSync } from './tmp-dir.ts';
11+
12+
const {
13+
mockAcquireXcodebuildSimulatorSetRedirect,
14+
mockCleanupTempFile,
15+
mockEnsureXctestrunArtifact,
16+
mockGetFreePort,
17+
mockIsProcessAlive,
18+
mockIsProcessGroupAlive,
19+
mockPrepareXctestrunWithEnv,
20+
mockReadProcessCommand,
21+
mockReadProcessStartTime,
22+
mockResolveExpectedRunnerCacheMetadata,
23+
mockResolveRunnerDerivedPath,
24+
mockRunAppleToolCommand,
25+
mockRunCmdBackground,
26+
mockRunXcrun,
27+
mockSendRunnerCommandOnce,
28+
mockSignalPidsBestEffort,
29+
mockSignalProcessGroupBestEffort,
30+
mockWaitForRunner,
31+
mockRedirectRelease,
32+
} = vi.hoisted(() => ({
33+
mockAcquireXcodebuildSimulatorSetRedirect: vi.fn(),
34+
mockCleanupTempFile: vi.fn(),
35+
mockEnsureXctestrunArtifact: vi.fn(),
36+
mockGetFreePort: vi.fn(),
37+
mockIsProcessAlive: vi.fn(),
38+
mockIsProcessGroupAlive: vi.fn(),
39+
mockPrepareXctestrunWithEnv: vi.fn(),
40+
// Deterministic owner identity: the real readProcessStartTime shells out to `ps` with a 1s
41+
// timeout that can miss under CPU contention and flip a live owner to dead.
42+
mockReadProcessCommand: vi.fn((_pid: number) => null as string | null),
43+
mockReadProcessStartTime: vi.fn((_pid: number) => 'fixed-test-owner-start-time' as string | null),
44+
mockResolveExpectedRunnerCacheMetadata: vi.fn(),
45+
mockResolveRunnerDerivedPath: vi.fn(),
46+
mockRunAppleToolCommand: vi.fn(),
47+
mockRunCmdBackground: vi.fn(),
48+
mockRunXcrun: vi.fn(),
49+
mockSendRunnerCommandOnce: vi.fn(),
50+
// The runner child pid is fabricated (4242): signal writes are mocked next to the liveness
51+
// reads so a made-up pid never reaches a sibling vitest fork (#1824).
52+
mockSignalPidsBestEffort: vi.fn(),
53+
mockSignalProcessGroupBestEffort: vi.fn(),
54+
mockWaitForRunner: vi.fn(),
55+
mockRedirectRelease: vi.fn(),
56+
}));
57+
58+
vi.mock('../runner-io.ts', async () => {
59+
const actual = await vi.importActual<typeof import('../runner-io.ts')>('../runner-io.ts');
60+
return { ...actual, cleanupTempFile: mockCleanupTempFile, getFreePort: mockGetFreePort };
61+
});
62+
63+
vi.mock('../runner-transport.ts', async () => {
64+
const actual =
65+
await vi.importActual<typeof import('../runner-transport.ts')>('../runner-transport.ts');
66+
return { ...actual, sendRunnerCommandOnce: mockSendRunnerCommandOnce };
67+
});
68+
69+
vi.mock('../runner-xctestrun.ts', async () => {
70+
const actual =
71+
await vi.importActual<typeof import('../runner-xctestrun.ts')>('../runner-xctestrun.ts');
72+
return {
73+
...actual,
74+
acquireXcodebuildSimulatorSetRedirect: mockAcquireXcodebuildSimulatorSetRedirect,
75+
ensureXctestrunArtifact: mockEnsureXctestrunArtifact,
76+
prepareXctestrunWithEnv: mockPrepareXctestrunWithEnv,
77+
resolveExpectedRunnerCacheMetadata: mockResolveExpectedRunnerCacheMetadata,
78+
resolveRunnerDerivedPath: mockResolveRunnerDerivedPath,
79+
};
80+
});
81+
82+
vi.mock('../runner-startup-transport.ts', async () => {
83+
const actual = await vi.importActual<typeof import('../runner-startup-transport.ts')>(
84+
'../runner-startup-transport.ts',
85+
);
86+
return { ...actual, waitForRunner: mockWaitForRunner };
87+
});
88+
89+
import {
90+
abortAllIosRunnerSessions,
91+
ensureRunnerSession,
92+
getRunnerSessionSnapshot,
93+
markRunnerSessionServed,
94+
releaseSpeculativeIosRunnerSession,
95+
} from '../runner-session.ts';
96+
import { withRunnerCommandId } from '../runner-contract.ts';
97+
98+
const TEST_OWNER_START_TIME = 'fixed-test-owner-start-time';
99+
100+
// Split from runner-session.test.ts, which is over the test-size tripwire: the speculative
101+
// session family (#2198: a proven observation-only plan retains no runner it did not ask for)
102+
// answers its own domain question here with the same seam scaffolding.
103+
beforeEach(async () => {
104+
appleRunnerTestHost.update({
105+
runCmdBackground: mockRunCmdBackground,
106+
isProcessAlive: mockIsProcessAlive,
107+
isProcessGroupAlive: mockIsProcessGroupAlive,
108+
readProcessCommand: mockReadProcessCommand,
109+
readProcessStartTime: mockReadProcessStartTime,
110+
signalPidsBestEffort: mockSignalPidsBestEffort,
111+
signalProcessGroupBestEffort: mockSignalProcessGroupBestEffort,
112+
runAppleToolCommand: mockRunAppleToolCommand,
113+
runXcrun: mockRunXcrun,
114+
leaseOwnerStateDir: () => undefined,
115+
classifyOwnerLiveness: makeClassifyOwnerLivenessViaMocks({
116+
isProcessAlive: (pid) => Boolean(mockIsProcessAlive(pid)),
117+
readProcessStartTime: (pid) => (mockReadProcessStartTime(pid) as string | null) ?? null,
118+
}),
119+
});
120+
await abortAllIosRunnerSessions();
121+
vi.resetAllMocks();
122+
process.env.AGENT_DEVICE_IOS_RUNNER_LEASE_DIR = mkdtempForTestSync(
123+
'agent-device-runner-lease-test-',
124+
);
125+
mockRunXcrun.mockResolvedValue({ exitCode: 0, stdout: '', stderr: '' });
126+
mockEnsureXctestrunArtifact.mockResolvedValue({
127+
xctestrunPath: '/tmp/base-runner.xctestrun',
128+
derived: '/tmp/derived',
129+
cache: 'hit',
130+
artifact: 'reused',
131+
buildMs: 0,
132+
xctestrunPathSource: 'cache',
133+
});
134+
mockGetFreePort.mockResolvedValue(8123);
135+
mockPrepareXctestrunWithEnv.mockResolvedValue({
136+
xctestrunPath: '/tmp/session-runner.xctestrun',
137+
jsonPath: '/tmp/session-runner.json',
138+
});
139+
mockResolveExpectedRunnerCacheMetadata.mockReturnValue({ schemaVersion: 1 });
140+
mockResolveRunnerDerivedPath.mockReturnValue('/tmp/derived');
141+
mockAcquireXcodebuildSimulatorSetRedirect.mockResolvedValue({ release: mockRedirectRelease });
142+
mockRunCmdBackground.mockReturnValue(makeBackgroundRunner(4242));
143+
mockRunAppleToolCommand.mockResolvedValue({ exitCode: 0, stdout: '', stderr: '' });
144+
mockIsProcessAlive.mockReturnValue(true);
145+
mockIsProcessGroupAlive.mockReturnValue(false);
146+
mockReadProcessCommand.mockReturnValue(null);
147+
mockReadProcessStartTime.mockImplementation((pid: number) =>
148+
pid === process.pid ? TEST_OWNER_START_TIME : null,
149+
);
150+
mockWaitForRunner.mockResolvedValue(runnerResponse({ uptimeMs: 1 }));
151+
});
152+
153+
test('a prewarm-started session is speculative until a command other than a readiness probe uses it', async () => {
154+
const device = { ...IOS_SIMULATOR, id: 'runner-session-speculative-sim' };
155+
156+
const session = await ensureRunnerSession(device, { speculative: true });
157+
assert.equal(session.speculative, true);
158+
159+
markRunnerSessionServed(session, withRunnerCommandId({ command: 'uptime' }));
160+
assert.equal(session.speculative, true, 'a readiness probe is not a use');
161+
162+
markRunnerSessionServed(session, withRunnerCommandId({ command: 'tap', x: 1, y: 1 }));
163+
assert.equal(session.speculative, false);
164+
assert.equal(await releaseSpeculativeIosRunnerSession(device.id), false);
165+
assert.notEqual(getRunnerSessionSnapshot(device.id), null, 'a served runner stays');
166+
});
167+
168+
test('releasing a speculative session stops it; a session a command asked for is kept', async () => {
169+
const speculative = { ...IOS_SIMULATOR, id: 'runner-session-speculative-release-sim' };
170+
const demanded = { ...IOS_SIMULATOR, id: 'runner-session-demanded-sim' };
171+
172+
await ensureRunnerSession(speculative, { speculative: true });
173+
await ensureRunnerSession(demanded, {});
174+
175+
assert.equal(await releaseSpeculativeIosRunnerSession(speculative.id), true);
176+
assert.equal(getRunnerSessionSnapshot(speculative.id), null);
177+
assert.equal(await releaseSpeculativeIosRunnerSession(demanded.id), false);
178+
assert.notEqual(getRunnerSessionSnapshot(demanded.id), null);
179+
assert.equal(await releaseSpeculativeIosRunnerSession('no-such-device'), false);
180+
});

0 commit comments

Comments
 (0)