Skip to content

Commit 17c933f

Browse files
committed
fix(open): admit the launch-only request shape before the lifecycle touches the device
Review round on #3928 (thymikee, third pass), non-blocking note taken as the stronger option. ADR 0037 rule 1 says a refused open never kills a running app, but only the owner refusal ran in assertOpenAdmitted: the URL-pair and no-app-target refusals still ran inside invokeApplicationOpen, so `open <bundle> <scheme://x> --relaunch --clear-app-state --capture-network` on a local iOS simulator closed the app and then failed with INVALID_ARGS. - One request-shape rule, `assertOpenRequestShape(positionals, execution)`, holds every launch-only check that needs no device: the positional count, the no-app-target refusals, the URL-pair refusals (first-argument, valid-URL, --launch-console, --capture-network) and the deep-link app refusals (--launch-console, --capture-network, --clear-app-state). assertOpenAdmitted enforces it, so every openApplication entry applies it before any relaunch close, runner stop, or runtime-hint write; invokeApplicationOpen keeps the same call for its folded and follow-up dispatches, and the open path now holds the one refusal that needs the platform itself (--launch-args on Linux). - Owner capability is still checked before request shape: where an option works at all is the more actionable refusal than the shape it was paired with. - Contract test: `a URL-pair relaunch carrying capture and clear-app-state is refused before any close` drives the review's exact command through a closeBeforeRelaunch local iOS-simulator binding and asserts INVALID_ARGS with no open, close, or setSetting call. Two table rows cover the deep-link app position for both launch-only options. - ADR 0037 rule 1 now states admission covers the owner capability and the request shape, so its sentence is true as written for every refusal it names.
1 parent c1ac863 commit 17c933f

7 files changed

Lines changed: 174 additions & 67 deletions

File tree

‎docs/adr/0037-ios-simulator-network-capture-probe.md‎

Lines changed: 8 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -10,13 +10,14 @@ Accepted (2026-10-23). Applies to iOS simulator app launches only.
1010
(built on demand, cached per content hash and toolchain) into the app process through
1111
`SIMCTL_CHILD_DYLD_INSERT_LIBRARIES`. Admission follows the owner that dispatches the open, not
1212
the device shape, and it happens before the lifecycle touches the device: `assertOpenAdmitted`
13-
runs first in every `openApplication` entry, so an owner that cannot inject the probe is refused
14-
with `UNSUPPORTED_OPERATION` and a typed `reason` before its relaunch close, runner stop, or
15-
runtime-hint write — a refused open never kills a running app. Only the local Apple lifecycle on
16-
an iOS simulator declares the capability, so a provider-backed iOS simulator (Limrun, TestMu)
17-
refuses the flag instead of launching without capture. Every other platform and every URL open
18-
refuse the flag. `--launch-console` admits the same way, and the same local-Simulator
19-
declaration gates both.
13+
runs first in every `openApplication` entry, enforcing both the owner capability and the
14+
request shape of the launch-only options (the positional and URL-pair checks that need no
15+
device), so an owner that cannot inject the probe, or a launch-only option on a request that
16+
cannot carry one, is refused before its relaunch close, runner stop, or runtime-hint write — a
17+
refused open never kills a running app. Only the local Apple lifecycle on an iOS simulator
18+
declares the capability, so a provider-backed iOS simulator (Limrun, TestMu) refuses the flag
19+
instead of launching without capture. Every other platform and every URL open refuse the flag.
20+
`--launch-console` admits the same way, and the same local-Simulator declaration gates both.
2021
2. The probe method-swizzles `-[NSURLSessionTask resume]`, observes each task to completion, and
2122
appends one JSON line per completed HTTP(S) task to the file named by
2223
`AGENT_DEVICE_NETWORK_CAPTURE_PATH` — the session's `network.jsonl`, one per session, replaced on

‎packages/contracts/src/application-lifecycle-interaction.test.ts‎

Lines changed: 65 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -37,7 +37,7 @@ const WEB_DEVICE: DeviceInfo = {
3737

3838
function interactorWithOpen(
3939
open: Interactor['open'] = async () => undefined,
40-
overrides: Partial<Pick<Interactor, 'close'>> = {},
40+
overrides: Partial<Pick<Interactor, 'close' | 'setSetting'>> = {},
4141
): Interactor {
4242
return {
4343
open,
@@ -154,6 +154,20 @@ test.each([
154154
execution: { clearAppState: true },
155155
message: /requires an app target, not a deep link/,
156156
},
157+
{
158+
name: 'launch console with a deep-link app target',
159+
device: IOS_SIMULATOR,
160+
positionals: ['example://home'],
161+
execution: { launchConsole: 'stdout' },
162+
message: /direct app/i,
163+
},
164+
{
165+
name: 'network capture with a deep-link app target',
166+
device: IOS_SIMULATOR,
167+
positionals: ['example://home'],
168+
execution: { networkCapturePath: '/sessions/one/network.jsonl' },
169+
message: /direct app launch/,
170+
},
157171
{
158172
name: 'network capture without an app',
159173
device: IOS_SIMULATOR,
@@ -250,6 +264,56 @@ for (const [name, execution, reason] of [
250264
});
251265
}
252266

267+
test('a URL-pair relaunch carrying capture and clear-app-state is refused before any close', async () => {
268+
// `open <bundle> <scheme://x> --relaunch --clear-app-state --capture-network`: the launch-only
269+
// options cannot ride a URL pair, and admission answers that from positionals and execution
270+
// alone — before the closeBeforeRelaunch owner closes the running app.
271+
const calls: string[] = [];
272+
const binding = bindLocalApplicationLifecycleInteractor({
273+
device: IOS_SIMULATOR,
274+
signal: new AbortController().signal,
275+
resolveInteractor: async () =>
276+
interactorWithOpen(
277+
async () => {
278+
calls.push('open');
279+
},
280+
{
281+
close: async () => {
282+
calls.push('close');
283+
},
284+
setSetting: async () => {
285+
calls.push('setSetting');
286+
},
287+
},
288+
),
289+
});
290+
const lifecycle = bindDirectApplicationLifecycle({
291+
binding,
292+
owner: 'Local',
293+
openTargetIdentity: 'bundle-id',
294+
closeBeforeRelaunch: true,
295+
});
296+
const refusal = await lifecycle
297+
.openApplication(
298+
openInput({
299+
relaunch: true,
300+
positionals: ['com.example.app', 'example://deal'],
301+
execution: {
302+
clearAppState: true,
303+
networkCapturePath: '/sessions/one/network.jsonl',
304+
},
305+
}),
306+
)
307+
.then(
308+
() => undefined,
309+
(error: unknown) => error,
310+
);
311+
expect(refusal).toBeInstanceOf(AppError);
312+
expect((refusal as AppError).code).toBe('INVALID_ARGS');
313+
expect((refusal as AppError).message).toMatch(/direct app launch/);
314+
expect(calls).toEqual([]);
315+
});
316+
253317
test('passes the session capture file to the interactor on a capture launch', async () => {
254318
let seen: Parameters<Interactor['open']>[1];
255319
await invokeApplicationOpen({

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

Lines changed: 97 additions & 55 deletions
Original file line numberDiff line numberDiff line change
@@ -150,17 +150,101 @@ const CAPTURE_NETWORK_UNADMITTED_MESSAGE =
150150
'--capture-network is supported only for a local iOS simulator app launch; this session owner cannot inject the capture probe';
151151

152152
/**
153-
* One admission step for the launch-only open options, called by every `openApplication` entry
154-
* before the lifecycle touches the device. `--launch-console` and `--capture-network` need an owner
155-
* that declared it can read simctl's console PTY or inject the capture probe; every other owner —
156-
* any provider, any non-iOS-simulator device — is refused with `UNSUPPORTED_OPERATION` and a typed
157-
* reason before its relaunch close, runner stop, or runtime-hint write runs. This is the whole
158-
* admission rule for those options (ADR 0037): the canonical open keeps only positional, URL, and
159-
* argument-shape checks.
153+
* The request-shape rule for the launch-only open options: what only `positionals` and `execution`
154+
* can answer, checked once and enforced twice — by {@link assertOpenAdmitted} before the lifecycle
155+
* touches the device, and by {@link invokeApplicationOpen} for its own folded and follow-up calls.
156+
* One helper per positional shape: no app target, a URL pair, or a single deep-link app target.
157+
* `--launch-console`, `--capture-network` and `--clear-app-state` act on the app the open launches,
158+
* so they refuse every shape but a direct app target, before any close, clear, or launch runs.
159+
*/
160+
function assertOpenRequestShape(
161+
positionals: readonly string[],
162+
execution: ApplicationLifecycleExecution,
163+
): void {
164+
if (positionals.length > 2) {
165+
throw new AppError('INVALID_ARGS', 'open accepts at most two arguments: <app|url> [url]');
166+
}
167+
const app = positionals[0];
168+
const url = positionals[1];
169+
if (app === undefined) {
170+
assertOpenDeviceOnlyRequest(execution);
171+
return;
172+
}
173+
if (url !== undefined) {
174+
assertOpenUrlPairRequest(app, url, execution);
175+
return;
176+
}
177+
if (isDeepLinkTarget(app)) {
178+
assertOpenDeepLinkAppRequest(execution);
179+
}
180+
}
181+
182+
function assertOpenDeviceOnlyRequest(execution: ApplicationLifecycleExecution): void {
183+
if (execution.launchConsole) {
184+
throw new AppError('INVALID_ARGS', '--launch-console requires an app target');
185+
}
186+
if (execution.networkCapturePath) {
187+
throw new AppError('INVALID_ARGS', CAPTURE_NETWORK_DIRECT_APP_ONLY_MESSAGE);
188+
}
189+
if (execution.launchArgs && execution.launchArgs.length > 0) {
190+
throw new AppError('INVALID_ARGS', '--launch-args requires an app target');
191+
}
192+
}
193+
194+
function assertOpenUrlPairRequest(
195+
app: string,
196+
url: string,
197+
execution: ApplicationLifecycleExecution,
198+
): void {
199+
if (isDeepLinkTarget(app)) {
200+
throw new AppError(
201+
'INVALID_ARGS',
202+
'open <app> <url> requires an app target as the first argument',
203+
);
204+
}
205+
if (!isDeepLinkTarget(url)) {
206+
throw new AppError('INVALID_ARGS', 'open <app> <url> requires a valid URL target');
207+
}
208+
if (execution.launchConsole) {
209+
throw new AppError('INVALID_ARGS', LAUNCH_CONSOLE_DIRECT_APP_ONLY_MESSAGE);
210+
}
211+
if (execution.networkCapturePath) {
212+
throw new AppError('INVALID_ARGS', CAPTURE_NETWORK_DIRECT_APP_ONLY_MESSAGE);
213+
}
214+
}
215+
216+
function assertOpenDeepLinkAppRequest(execution: ApplicationLifecycleExecution): void {
217+
if (execution.launchConsole) {
218+
throw new AppError('INVALID_ARGS', LAUNCH_CONSOLE_DIRECT_APP_ONLY_MESSAGE);
219+
}
220+
if (execution.networkCapturePath) {
221+
throw new AppError('INVALID_ARGS', CAPTURE_NETWORK_DIRECT_APP_ONLY_MESSAGE);
222+
}
223+
if (execution.clearAppState) {
224+
throw new AppError(
225+
'INVALID_ARGS',
226+
'Clearing app state requires an app target, not a deep link.',
227+
);
228+
}
229+
}
230+
231+
/**
232+
* One admission step for the open command, called by every `openApplication` entry before the
233+
* lifecycle touches the device. It enforces the owner capability and the request shape of the
234+
* launch-only options: `--launch-console` and `--capture-network` need an owner that declared it
235+
* can read simctl's console PTY or inject the capture probe, and every other owner — any provider,
236+
* any non-iOS-simulator device — is refused with `UNSUPPORTED_OPERATION` and a typed reason; the
237+
* positional and URL-pair checks in {@link assertOpenRequestShape} then refuse a launch-only option
238+
* on a request that cannot carry one, with `INVALID_ARGS`. The owner answers first because where an
239+
* option works at all is the more actionable refusal. So no refusal — of an owner that cannot honor
240+
* an option or of a malformed launch-only request — ever follows a relaunch close, a runner stop,
241+
* or a runtime-hint write (ADR 0037). The canonical open keeps the same shape rule for its own
242+
* folded and follow-up dispatches, plus the one refusal that needs the platform itself.
160243
*/
161244
export function assertOpenAdmitted(
162245
binding: Pick<ApplicationLifecycleInteractorBinding, 'device' | 'supportsLocalSimulatorLaunch'>,
163246
execution: ApplicationLifecycleExecution,
247+
positionals: readonly string[],
164248
): void {
165249
if (execution.launchConsole && !binding.supportsLocalSimulatorLaunch) {
166250
throw new AppError('UNSUPPORTED_OPERATION', LAUNCH_CONSOLE_UNADMITTED_MESSAGE, {
@@ -174,6 +258,7 @@ export function assertOpenAdmitted(
174258
deviceId: binding.device.id,
175259
});
176260
}
261+
assertOpenRequestShape(positionals, execution);
177262
}
178263

179264
/**
@@ -191,11 +276,11 @@ export async function invokeApplicationOpen(
191276
}>,
192277
): Promise<ApplicationLaunchReport | void> {
193278
const { device, positionals, execution } = params;
194-
assertOpenPositionals(positionals);
279+
assertOpenRequestShape(positionals, execution);
195280
const app = positionals[0];
196281
const url = positionals[1];
197282
if (!app) {
198-
await invokeDeviceOpen(params);
283+
await params.interactor.openDevice();
199284
return;
200285
}
201286
assertOpenDeviceSupport(device, execution);
@@ -212,31 +297,12 @@ type DirectOpenParameters = Readonly<{
212297
terminateRunningApp?: boolean;
213298
}>;
214299

215-
function assertOpenPositionals(positionals: readonly string[]): void {
216-
if (positionals.length > 2) {
217-
throw new AppError('INVALID_ARGS', 'open accepts at most two arguments: <app|url> [url]');
218-
}
219-
}
220-
221-
async function invokeDeviceOpen(params: DirectOpenParameters): Promise<void> {
222-
if (params.execution.launchConsole) {
223-
throw new AppError('INVALID_ARGS', '--launch-console requires an app target');
224-
}
225-
if (params.execution.networkCapturePath) {
226-
throw new AppError('INVALID_ARGS', CAPTURE_NETWORK_DIRECT_APP_ONLY_MESSAGE);
227-
}
228-
if (params.execution.launchArgs && params.execution.launchArgs.length > 0) {
229-
throw new AppError('INVALID_ARGS', '--launch-args requires an app target');
230-
}
231-
await params.interactor.openDevice();
232-
}
233-
234300
function assertOpenDeviceSupport(
235301
device: DeviceInfo,
236302
execution: ApplicationLifecycleExecution,
237303
): void {
238-
// The launch-only options were admitted by owner before this point (assertOpenAdmitted); what
239-
// remains here is what only the canonical open can see: the target shape of the request.
304+
// The launch-only options were admitted by shape and by owner before this point
305+
// (assertOpenAdmitted); what remains here is the one refusal that needs the platform itself.
240306
if (device.platform === 'linux' && execution.launchArgs && execution.launchArgs.length > 0) {
241307
throw new AppError('UNSUPPORTED_OPERATION', '--launch-args is not supported on Linux.');
242308
}
@@ -247,21 +313,6 @@ async function invokeApplicationUrlOpen(
247313
app: string,
248314
url: string,
249315
): Promise<ApplicationLaunchReport | void> {
250-
if (isDeepLinkTarget(app)) {
251-
throw new AppError(
252-
'INVALID_ARGS',
253-
'open <app> <url> requires an app target as the first argument',
254-
);
255-
}
256-
if (!isDeepLinkTarget(url)) {
257-
throw new AppError('INVALID_ARGS', 'open <app> <url> requires a valid URL target');
258-
}
259-
if (params.execution.launchConsole) {
260-
throw new AppError('INVALID_ARGS', LAUNCH_CONSOLE_DIRECT_APP_ONLY_MESSAGE);
261-
}
262-
if (params.execution.networkCapturePath) {
263-
throw new AppError('INVALID_ARGS', CAPTURE_NETWORK_DIRECT_APP_ONLY_MESSAGE);
264-
}
265316
return await params.interactor.open(app, {
266317
activity: params.execution.activity,
267318
appBundleId: params.appBundleId,
@@ -276,16 +327,7 @@ async function invokeApplicationTargetOpen(
276327
app: string,
277328
): Promise<ApplicationLaunchReport | void> {
278329
const { execution, interactor } = params;
279-
if (execution.launchConsole && isDeepLinkTarget(app)) {
280-
throw new AppError('INVALID_ARGS', LAUNCH_CONSOLE_DIRECT_APP_ONLY_MESSAGE);
281-
}
282330
if (execution.clearAppState) {
283-
if (isDeepLinkTarget(app)) {
284-
throw new AppError(
285-
'INVALID_ARGS',
286-
'Clearing app state requires an app target, not a deep link.',
287-
);
288-
}
289331
await interactor.setSetting('clear-app-state', 'clear', app);
290332
}
291333
return await interactor.open(app, {
@@ -355,7 +397,7 @@ async function openDirectApplication(
355397
input: OpenApplicationInput,
356398
): Promise<OpenApplicationOutcome> {
357399
const { binding } = params;
358-
assertOpenAdmitted(binding, input.execution);
400+
assertOpenAdmitted(binding, input.execution, input.positionals);
359401
const interactor = await binding.resolveInteractor(input.execution, input.appBundleId);
360402
if (params.closeBeforeRelaunch && input.relaunch && input.target !== undefined) {
361403
await invokeApplicationClose({

‎packages/daemon/src/__tests__/support/application-lifecycle-runtime-harness.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -145,7 +145,7 @@ function applicationLifecycleRuntimeFixtureProviderOperations(
145145
}),
146146
prepareApplicationOpen: async () => undefined,
147147
openApplication: async (input) => {
148-
assertOpenAdmitted(binding, input.execution);
148+
assertOpenAdmitted(binding, input.execution, input.positionals);
149149
await invokeApplicationOpen({
150150
device,
151151
interactor: await binding.resolveInteractor(input.execution, input.appBundleId),

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

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -109,7 +109,7 @@ async function openAndroidApplication(
109109
input: OpenApplicationInput,
110110
): Promise<OpenApplicationOutcome> {
111111
const timing: MutableOpenTiming = {};
112-
assertOpenAdmitted(binding, input.execution);
112+
assertOpenAdmitted(binding, input.execution, input.positionals);
113113
const relaunching = input.relaunch && Boolean(input.target);
114114
const relaunchOwner = relaunching ? input.appBundleId : undefined;
115115
if (relaunchOwner) {

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

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -123,7 +123,7 @@ async function openAppleApplication(
123123
observation: LaunchObservationPort | undefined,
124124
): Promise<OpenApplicationOutcome> {
125125
const timing: MutableOpenTiming = {};
126-
assertOpenAdmitted(binding, input.execution);
126+
assertOpenAdmitted(binding, input.execution, input.positionals);
127127
const localIosSimulator = isIosSimulator(binding.device);
128128
const runner = createRunnerPrewarm(host, binding, input, timing);
129129
const policy = resolveRunnerPrewarmPolicy(binding.device, input, localIosSimulator);

‎test/integration/provider-scenarios/provider-device-runtime.fixtures.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -209,7 +209,7 @@ function providerScenarioApplicationLifecycle(
209209
}),
210210
prepareApplicationOpen: async () => undefined,
211211
openApplication: async (input) => {
212-
assertOpenAdmitted(binding, input.execution);
212+
assertOpenAdmitted(binding, input.execution, input.positionals);
213213
if (input.relaunch && input.target) {
214214
await invokeApplicationClose({
215215
device,

0 commit comments

Comments
 (0)