Skip to content

Commit bd0cae4

Browse files
thymikeeclaude
andcommitted
refactor(apple): let the classifier own the launch-log verdict
The connect loop decided a boot was terminal with its own bless-signature check, a copy of the row's line matching that ignored row order. On a scoped-set launch whose tail held both signatures the loop stopped while the built error carried `simulator_set_destination_not_found`, whose verdict was retryable, so each remaining attempt re-threw without dialing until the deadline. Now the verdict is whatever `classifyRunnerStartupFailure` returns over the tail: a row declares the cause it names in the message, the classifier returns it, and the loop throws the built error only when `shouldRetryRunnerConnectError` says a retry cannot help. The scoped-set destination cause gets the same fast path, the transport knows no hub specifics, and the two message helpers and the signature predicate are gone. Refs #3449, #3739 review round 2. Co-Authored-By: Claude <[email protected]>
1 parent d91886f commit bd0cae4

6 files changed

Lines changed: 196 additions & 101 deletions

File tree

‎packages/platform-apple/src/runner/__tests__/runner-error-classification.test.ts‎

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -283,6 +283,41 @@ test('a refused connection still restarts and rebuilds without the service-hub r
283283
assert.equal(shouldRebuildCachedRunnerArtifact(refused), true);
284284
});
285285

286+
test('a scoped-set destination this Xcode cannot resolve is terminal on every recovery axis', () => {
287+
// The other cause a launch log names. The set is on the command, so a retry, a restart, or a fresh
288+
// build resolves nothing, and the connect loop has to stop on the attempt that reads the log — the
289+
// same terminal reading the service-hub cause gets.
290+
const destinationFailure = commandFailed('Runner did not accept connection', {
291+
reason: 'simulator_set_destination_not_found',
292+
runnerConnectFailureReason: 'runner_connect_refused',
293+
dispatched: 'no',
294+
simulatorSetPath: '/Users/dev/Library/Developer/CoreSimulator/Sets/foo.json',
295+
});
296+
assert.equal(shouldRetryRunnerConnectError(destinationFailure), false);
297+
assert.equal(isRetryableRunnerError(destinationFailure), false);
298+
assert.equal(shouldRestartRunnerBeforeCommandSend(destinationFailure, SNAPSHOT), false);
299+
assert.equal(shouldRebuildCachedRunnerArtifact(destinationFailure), false);
300+
assert.equal(
301+
shouldRestartRunnerAfterReadinessPreflight(
302+
commandFailed('Runner readiness refused', {
303+
reason: 'simulator_set_destination_not_found',
304+
runnerReadinessPreflightFailed: true,
305+
}),
306+
),
307+
false,
308+
);
309+
});
310+
311+
test('the reason in foreign text marks nothing terminal', () => {
312+
// The verdict keys on the reason the launch paths publish. A runner response or tool transcript that
313+
// merely repeats the words cannot order a failure non-retryable.
314+
const echoed = commandFailed(
315+
'Runner did not accept connection: simulator_set_destination_not_found',
316+
{ stderr: 'DTServiceHubClient failed to bless service hub for simulator' },
317+
);
318+
assert.equal(shouldRetryRunnerConnectError(echoed), true);
319+
});
320+
286321
test('a device that is busy connecting is a terminal connect verdict', () => {
287322
assert.equal(
288323
shouldRetryRunnerConnectError(commandFailed('Device is busy (Connecting to Simulator)')),

‎packages/platform-apple/src/runner/__tests__/runner-startup-transport-service-hub.test.ts‎

Lines changed: 51 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -20,7 +20,11 @@ import {
2020
iosSimulator,
2121
runnerTransportResponse,
2222
} from './runner-transport.fixtures.ts';
23-
import { buildFixtureById } from './runner-startup-failure-fixtures.ts';
23+
import {
24+
CAPTURED_LAUNCH_DESTINATION_NOT_FOUND_OUTPUT,
25+
CAPTURED_SCOPED_SIMULATOR,
26+
buildFixtureById,
27+
} from './runner-startup-failure-fixtures.ts';
2428
import { mkdtempForTestSync } from './tmp-dir.ts';
2529

2630
beforeEach(resetAllProcessMemosForTests);
@@ -164,6 +168,52 @@ test('a bless refusal already in the launch log ends the connect loop on its fir
164168
);
165169
});
166170

171+
test("one tail holding two launch-log causes gets the classifier's own winner, terminal", async () => {
172+
// The row order decides, not the loop. A scoped-set launch whose log holds both the bless refusal and
173+
// the missing destination reads as `simulator_set_destination_not_found`, the row that comes first.
174+
// A pre-check of the loop's own would see the bless, order the stop, and hand back an error whose
175+
// reason says otherwise — and the first fix did exactly that, so each remaining attempt re-threw
176+
// without dialing until the deadline. One classifier over the tail cannot produce that pair.
177+
const fetchSpy = vi.fn(async () => {
178+
throw Object.assign(new Error('connect ECONNREFUSED 127.0.0.1:8100'), { code: 'ECONNREFUSED' });
179+
});
180+
vi.stubGlobal('fetch', fetchSpy);
181+
const scopedSimulator = {
182+
...iosSimulator,
183+
id: CAPTURED_SCOPED_SIMULATOR.udid,
184+
simulatorSetPath: CAPTURED_SCOPED_SIMULATOR.setWithoutUdid,
185+
};
186+
const session = {
187+
...sessionWithLaunchLog(`${CAPTURED_LAUNCH_DESTINATION_NOT_FOUND_OUTPUT}\n${BLESS_LOG}`, null),
188+
device: scopedSimulator,
189+
deviceId: scopedSimulator.id,
190+
};
191+
const startedAt = Date.now();
192+
193+
const error = await waitForRunner(
194+
scopedSimulator,
195+
RUNNER_ENDPOINT_FIXTURE,
196+
{ command: 'snapshot' },
197+
undefined,
198+
CONNECT_BUDGET_MS,
199+
session,
200+
).catch((error: unknown) => error as AppError);
201+
202+
const elapsedMs = Date.now() - startedAt;
203+
assert.ok(error instanceof AppError);
204+
// The reason and the message agree because one row produced both, and the verdict beside them is the
205+
// terminal one that class shares, so the loop stopped rather than re-throwing at the deadline.
206+
assert.equal(error.details?.reason, 'simulator_set_destination_not_found');
207+
assert.ok(error.message.includes(CAPTURED_SCOPED_SIMULATOR.setWithoutUdid), error.message);
208+
assert.doesNotMatch(error.message, /simulator service/);
209+
assert.equal(shouldRetryRunnerConnectError(error), false);
210+
assert.equal(fetchSpy.mock.calls.length, 0);
211+
assert.ok(
212+
elapsedMs < CONNECT_BUDGET_MS / 2,
213+
`expected the failure well before its ${CONNECT_BUDGET_MS}ms deadline, took ${elapsedMs}ms`,
214+
);
215+
});
216+
167217
test('a bless refusal in an older runner generation does not end this launch early', async () => {
168218
// The log is append-only across launches, so a bless refusal the previous launch wrote is not
169219
// evidence about this one (#2681). The session's tail reader starts at this generation's offset.

‎packages/platform-apple/src/runner/runner-artifact.ts‎

Lines changed: 20 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -21,8 +21,8 @@ import type { DeviceInfo } from '@agent-device/kernel/device';
2121
import { classifyRunnerStartupFailure } from './runner-error-classification.ts';
2222
import { logChunk } from './runner-io.ts';
2323
import {
24+
runnerLaunchLogClassificationDetails,
2425
runnerSimulatorSetFailureDetails,
25-
simulatorSetDestinationNotFoundMessage,
2626
xcodebuildDestinationArgs,
2727
} from './runner-device-set.ts';
2828
import {
@@ -925,33 +925,31 @@ async function buildRunnerXctestrun(
925925
if (isRequestCanceledError(error)) throw error;
926926
const appErr =
927927
error instanceof AppError ? error : new AppError('COMMAND_FAILED', String(error));
928-
const simulatorSet = runnerSimulatorSetFailureDetails(device);
929-
// The reason and the hint beside it come from one classifier (#2680), so the reason a caller
930-
// switches on can never disagree with the advice it is handed.
931-
const { reason, hint, matched } = classifyRunnerStartupFailure(
932-
new AppError(appErr.code, appErr.message, { ...appErr.details, ...simulatorSet }),
928+
const publishedSimulatorSet = runnerSimulatorSetFailureDetails(device);
929+
// The reason, the hint, and any cause named in the message all come from one classifier (#2680), so
930+
// the reason a caller switches on can never disagree with the advice or the sentence beside it.
931+
const classificationDetails = runnerLaunchLogClassificationDetails(device);
932+
const { reason, hint, messageSuffix, matched } = classifyRunnerStartupFailure(
933+
new AppError(appErr.code, appErr.message, {
934+
...appErr.details,
935+
...classificationDetails,
936+
}),
933937
);
934938
const hostDeadlineHit = isCommandTimeoutError(appErr);
935939
// `startupRuleMatched` travels with the verdict: this wrapper buries the tool's text a level too
936940
// deep for the rows to read again, and whether a row spoke is not recoverable from the reason
937941
// alone (#2690 review). The device's own state is attached further out, by the startup catch that
938942
// can see this build and the launch after it.
939943
const message = 'xcodebuild build-for-testing failed';
940-
throw new AppError(
941-
'COMMAND_FAILED',
942-
reason === 'simulator_set_destination_not_found'
943-
? simulatorSetDestinationNotFoundMessage(message, device, simulatorSet)
944-
: message,
945-
{
946-
reason,
947-
error: appErr.message,
948-
details: appErr.details,
949-
logPath: options.logPath,
950-
hint,
951-
startupRuleMatched: matched,
952-
startupHostDeadlineHit: hostDeadlineHit,
953-
...simulatorSet,
954-
},
955-
);
944+
throw new AppError('COMMAND_FAILED', messageSuffix ? `${message}: ${messageSuffix}` : message, {
945+
reason,
946+
error: appErr.message,
947+
details: appErr.details,
948+
logPath: options.logPath,
949+
hint,
950+
startupRuleMatched: matched,
951+
startupHostDeadlineHit: hostDeadlineHit,
952+
...publishedSimulatorSet,
953+
});
956954
}
957955
}

‎packages/platform-apple/src/runner/runner-device-set.ts‎

Lines changed: 10 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -43,13 +43,16 @@ export function runnerSimulatorSetFailureDetails(
4343
}
4444

4545
/**
46-
* Names the simulator and the scoped set behind a `simulator_set_destination_not_found`, and the Xcode
47-
* when this process has read its version.
46+
* The classification inputs one device's launch hands `classifyRunnerStartupFailure`. Besides the
47+
* scoped set and the Xcode this process already read, it carries the simulator the launch was built
48+
* for, which the row that reports a missing destination names in its own sentence.
49+
*
50+
* An input, not a published shape: callers spread it into the error they classify and publish only
51+
* {@link runnerSimulatorSetFailureDetails} beside their failure. The simulator is in the sentence that
52+
* sentence builds, so the row is the only reader of `simulatorUdid`.
4853
*/
49-
export function simulatorSetDestinationNotFoundMessage(
50-
message: string,
54+
export function runnerLaunchLogClassificationDetails(
5155
device: DeviceInfo,
52-
details: RunnerSimulatorSetFailureDetails,
53-
): string {
54-
return `${message}: xcodebuild found no simulator ${device.id} in simulator set ${details.simulatorSetPath}${details.xcodeVersion === undefined ? '' : ` with Xcode ${details.xcodeVersion}`}`;
56+
): RunnerSimulatorSetFailureDetails & { simulatorUdid: string } {
57+
return { ...runnerSimulatorSetFailureDetails(device), simulatorUdid: device.id };
5558
}

‎packages/platform-apple/src/runner/runner-error-classification.ts‎

Lines changed: 53 additions & 36 deletions
Original file line numberDiff line numberDiff line change
@@ -109,12 +109,14 @@ const hasRunnerConnectFailureReason =
109109
(details) =>
110110
details.runnerConnectFailureReason === reason;
111111
/**
112-
* The terminal verdict of a runner launch whose simulator service this macOS refused to load. It keys
113-
* on the reason the launch paths publish, never on the bless sentence they quote, so foreign text
114-
* carrying Xcode's own wording cannot, on its own, mark a failure terminal.
112+
* The terminal verdict of a runner launch whose cause the launch output itself names — the simulator
113+
* service this macOS refused to load, or a scoped-set destination this Xcode cannot resolve. It keys on
114+
* the reason the launch paths publish, never on the tool sentence they quote, so foreign text carrying
115+
* Xcode's own wording cannot, on its own, mark a failure terminal.
115116
*/
116-
const hasSimulatorServiceHubFailure: RunnerErrorDetailsMatch = (details) =>
117-
details.reason === SIMULATOR_SERVICE_HUB_UNAVAILABLE_REASON;
117+
const hasLaunchLogCauseFailure: RunnerErrorDetailsMatch = (details) =>
118+
details.reason === SIMULATOR_SERVICE_HUB_UNAVAILABLE_REASON ||
119+
details.reason === SIMULATOR_SET_DESTINATION_NOT_FOUND_REASON;
118120
/**
119121
* The preflight marks whatever it was waiting on when it stopped, and one of the things it waits on
120122
* is a caller that stopped waiting. A canceled request is not a wedged runner: the restart this
@@ -205,42 +207,25 @@ export type RunnerDeviceReadinessFailureReason =
205207
* selects an Xcode that supports its macOS. AMFI's refusal is visible only as the bless line in the
206208
* launch output, which is why the row keys on that phrase and why no host-side preflight exists.
207209
*/
208-
export const SIMULATOR_SERVICE_HUB_UNAVAILABLE_REASON: RunnerStartupFailureReason =
210+
const SIMULATOR_SERVICE_HUB_UNAVAILABLE_REASON: RunnerStartupFailureReason =
209211
'simulator_service_hub_unavailable';
210212

213+
/**
214+
* The reason for a scoped-set launch whose simulator this Xcode cannot resolve. The set is named on the
215+
* command, so a launch that finds no matching destination fails identically on every retry.
216+
*/
217+
const SIMULATOR_SET_DESTINATION_NOT_FOUND_REASON: RunnerStartupFailureReason =
218+
'simulator_set_destination_not_found';
219+
211220
/**
212221
* The bless refusal, in the two phrases Xcode writes on one line: the client that failed and the
213-
* bless it failed to perform. Declared once because the classifier row reads it and the connect loop
214-
* checks the launch tail for it; the two cannot disagree about what a terminal boot looks like. The
215-
* loop's check must stay no broader than the row's, or it would order a verdict the row refuses to
216-
* prove.
222+
* bless it failed to perform.
217223
*/
218224
const SIMULATOR_SERVICE_HUB_BLESS_MATCH = [
219225
'dtservicehubclient',
220226
'failed to bless service hub',
221227
] as const;
222228

223-
/**
224-
* Whether runner launch output carries the bless refusal. The connect loop asks this before it pays
225-
* for a full startup classification, which resolves a simulator-set cause through a toolchain probe.
226-
* Same one-line rule the row applies, over the same text.
227-
*/
228-
export function isSimulatorServiceHubLaunchOutput(output: string): boolean {
229-
const normalized = output.toLowerCase();
230-
return normalized
231-
.split('\n')
232-
.some((line) => SIMULATOR_SERVICE_HUB_BLESS_MATCH.every((part) => line.includes(part)));
233-
}
234-
235-
/**
236-
* Names the cause in the message beside the connect-shaped failure the bless refusal produced. The
237-
* reason and hint come from {@link classifyRunnerStartupFailure}; this only folds the cause into the
238-
* sentence the caller reads first.
239-
*/
240-
export function simulatorServiceHubFailureMessage(message: string): string {
241-
return `${message}: this Xcode cannot start its simulator service on this macOS`;
242-
}
243-
244229
/**
245230
* The reason a startup failure carries when no rule proves a cause. Its hint is deliberately the
246231
* cache-recovery advice rather than anything about signing: an unclassified build is not evidence of
@@ -264,6 +249,18 @@ type RunnerErrorRule = {
264249
buildFailure?: {
265250
reason: RunnerStartupFailureReason;
266251
hint: string;
252+
/**
253+
* The cause this row names inside the sentence the caller publishes, in the words the tool itself
254+
* used. A row that carries it is a cause the startup paths can name from the launch output alone,
255+
* so this module stays the only text matcher: a failure site deciding which causes deserve their own
256+
* sentence would be a second classifier. Rows without it travel as a reason beside the caller's
257+
* sentence.
258+
*
259+
* `details` is what the caller handed the classifier, so a row naming a per-launch fact reads it from
260+
* there ({@link runnerLaunchLogClassificationDetails}). Returning undefined when a fact is missing
261+
* leaves the caller's sentence standing.
262+
*/
263+
messageSuffix?: (details: AppErrorDetails) => string | undefined;
267264
};
268265
};
269266

@@ -336,10 +333,14 @@ export const RUNNER_ERROR_RULES: readonly RunnerErrorRule[] = [
336333
verdicts: { retryable: false, connectRetry: false, artifactSuspect: false },
337334
},
338335
{
339-
// A boot whose simulator service the host refused is not cured by wiping derived data, and no
340-
// restart or resend can make AMFI load a binary this macOS rejects.
341-
reason: 'simulator_service_hub_unavailable',
342-
match: { code: 'COMMAND_FAILED', details: hasSimulatorServiceHubFailure },
336+
// The terminal reading of every cause a launch log can name: a simulator service this macOS refuses
337+
// to load, or a scoped-set destination this Xcode cannot resolve. Neither is cured by a connect
338+
// retry, a session restart, or a rebuilt artifact, and this row has to precede the generic
339+
// `runner_connect_refused` row to say so on a connect-shaped failure carrying one of them. It keys
340+
// on the reason the launch paths publish, never on the tool sentence they quote, so foreign text
341+
// wearing Xcode's own wording cannot mark a failure terminal on its own.
342+
reason: 'runner_launch_log_cause',
343+
match: { code: 'COMMAND_FAILED', details: hasLaunchLogCauseFailure },
343344
verdicts: {
344345
retryable: false,
345346
connectRetry: false,
@@ -455,6 +456,10 @@ export const RUNNER_ERROR_RULES: readonly RunnerErrorRule[] = [
455456
buildFailure: {
456457
reason: 'simulator_set_destination_not_found',
457458
hint: 'Check that the simulator still exists in the --ios-simulator-device-set this error names (`xcrun simctl --set <set> list devices`). If it does, the Xcode this error names no longer honors -DVTSimulatorSetLocation, so use a simulator in the default set.',
459+
messageSuffix: (details) =>
460+
typeof details.simulatorSetPath === 'string' && typeof details.simulatorUdid === 'string'
461+
? `xcodebuild found no simulator ${details.simulatorUdid} in simulator set ${details.simulatorSetPath}${typeof details.xcodeVersion === 'string' ? ` with Xcode ${details.xcodeVersion}` : ''}`
462+
: undefined,
458463
},
459464
},
460465
{
@@ -471,6 +476,7 @@ export const RUNNER_ERROR_RULES: readonly RunnerErrorRule[] = [
471476
buildFailure: {
472477
reason: SIMULATOR_SERVICE_HUB_UNAVAILABLE_REASON,
473478
hint: 'This Xcode cannot start its simulator service on this macOS: macOS refuses to load its DTServiceHub. Select an Xcode that supports this macOS on the daemon host (`xcode-select -s /Applications/Xcode.app`, or DEVELOPER_DIR=/Applications/Xcode.app for the daemon process), then retry. Updating Xcode is the fix; restarting the runner or clearing derived data cannot change it.',
479+
messageSuffix: () => 'this Xcode cannot start its simulator service on this macOS',
474480
},
475481
},
476482
{
@@ -802,7 +808,12 @@ export function classifyRunnerStartupFailure(error: unknown): RunnerStartupClass
802808
const buildFailure = rule.buildFailure;
803809
if (!buildFailure) continue;
804810
if (matchesRunnerErrorRule(error, rule.match)) {
805-
return { reason: buildFailure.reason, hint: buildFailure.hint, matched: true };
811+
return {
812+
reason: buildFailure.reason,
813+
hint: buildFailure.hint,
814+
messageSuffix: buildFailure.messageSuffix?.(error.details ?? {}),
815+
matched: true,
816+
};
806817
}
807818
}
808819
}
@@ -822,6 +833,12 @@ export function classifyRunnerStartupFailure(error: unknown): RunnerStartupClass
822833
export type RunnerStartupClassification = Readonly<{
823834
reason: RunnerStartupFailureReason;
824835
hint: string;
836+
/**
837+
* The cause in the tool's own words, when the matched row declares one ({@link RunnerErrorRule}). A
838+
* caller publishing a sentence about this failure appends it, so the words naming the cause come from
839+
* the same row that named the reason — never from a failure site choosing its own phrasing.
840+
*/
841+
messageSuffix?: string;
825842
/**
826843
* False only when no rule row matched at all. The catch that publishes this verdict carries it on
827844
* `details.startupRuleMatched`, which is the half a caller cannot recover from the reason alone.

0 commit comments

Comments
 (0)