Skip to content

Commit d91886f

Browse files
thymikeeclaude
andcommitted
fix(apple): fail a bless-refused runner launch at the connect attempt
The refusal names its cause only in runner.log, and the classifier read that log after the connect loop had spent its whole deadline, so the reporter's ~90 seconds of futile retries survived the first fix. Read the launch tail at each attempt while the session has yet to answer and stop there; the tail is bounded to what an error would quote, read from this generation's offset, and costs no subprocess. Also completes the documented reason vocabulary, which was missing simulator_set_destination_not_found at both prose surfaces, and guards it: the union in runner-error-classification.ts is now checked against both by test/repo-guards/runner-startup-reason-docs.test.ts. Refs #3449, #3739 review round 1. Co-Authored-By: Claude <[email protected]>
1 parent e003dea commit d91886f

7 files changed

Lines changed: 250 additions & 9 deletions

File tree

‎packages/platform-apple/src/runner/__tests__/runner-startup-failure-fixtures.ts‎

Lines changed: 5 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -25,9 +25,11 @@ import { IOS_SIMULATOR } from './device-fixtures.ts';
2525
* - `invented-shape` — no shipped trigger and no capture. The entry exists to exercise a rule and
2626
* makes no claim about wording xcodebuild prints.
2727
*
28-
* Until Phase B captures the real runs, every entry is `unobserved` for `xcodeVersion` and carries
29-
* no `command`: an invocation we did not run is not provenance. Nothing in the classifier reads
30-
* these fields; they exist so a reason can be traced to an observation instead of to a guess.
28+
* The two kinds with no observation behind the invocation — `shipped-sniff-trigger` and
29+
* `invented-shape` — are `unobserved` for `xcodeVersion` and carry no `command`: an invocation we did
30+
* not run is not provenance. `captured` records both, and `reported-log-excerpt` records the version
31+
* its reporter stated and no command. Nothing in the classifier reads these fields; they exist so a
32+
* reason can be traced to an observation instead of to a guess.
3133
*
3234
* Blocked on the host, not unexamined. One Phase B run on `thymikee-iphone` / Xcode 26.2 settled the
3335
* shape question these rows were held on — `No profiles for '<id>' were found` arrives as one long

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

Lines changed: 103 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -15,7 +15,11 @@ import {
1515
shouldRestartRunnerBeforeCommandSend,
1616
shouldRetryRunnerConnectError,
1717
} from '../runner-error-classification.ts';
18-
import { RUNNER_ENDPOINT_FIXTURE, iosSimulator } from './runner-transport.fixtures.ts';
18+
import {
19+
RUNNER_ENDPOINT_FIXTURE,
20+
iosSimulator,
21+
runnerTransportResponse,
22+
} from './runner-transport.fixtures.ts';
1923
import { buildFixtureById } from './runner-startup-failure-fixtures.ts';
2024
import { mkdtempForTestSync } from './tmp-dir.ts';
2125

@@ -125,6 +129,104 @@ test('a still-alive xcodebuild whose log carries the bless refusal fails the con
125129
assert.equal(shouldRebuildCachedRunnerArtifact(error), false);
126130
});
127131

132+
/** A connect budget far longer than the bless refusal needs, so its arrival is a claim about timing. */
133+
const CONNECT_BUDGET_MS = 5_000;
134+
135+
test('a bless refusal already in the launch log ends the connect loop on its first attempt', async () => {
136+
// The reporters' 90 seconds came from spending the whole connect budget on a boot that had already
137+
// said why it would never serve a command (#3449). The signature appears in `runner.log` within the
138+
// first seconds of the launch, so the loop has to read it and stop.
139+
const fetchSpy = vi.fn(async () => {
140+
throw Object.assign(new Error('connect ECONNREFUSED 127.0.0.1:8100'), { code: 'ECONNREFUSED' });
141+
});
142+
vi.stubGlobal('fetch', fetchSpy);
143+
const session = sessionWithLaunchLog(BLESS_LOG, null);
144+
const startedAt = Date.now();
145+
146+
const error = await waitForRunner(
147+
iosSimulator,
148+
RUNNER_ENDPOINT_FIXTURE,
149+
{ command: 'snapshot' },
150+
undefined,
151+
CONNECT_BUDGET_MS,
152+
session,
153+
).catch((error: unknown) => error as AppError);
154+
155+
const elapsedMs = Date.now() - startedAt;
156+
assert.ok(error instanceof AppError);
157+
assert.equal(error.details?.reason, 'simulator_service_hub_unavailable');
158+
// No connect attempt is dialed once the boot is known terminal, and the failure arrives with most
159+
// of the budget unspent rather than at its deadline.
160+
assert.equal(fetchSpy.mock.calls.length, 0);
161+
assert.ok(
162+
elapsedMs < CONNECT_BUDGET_MS / 2,
163+
`expected the failure well before its ${CONNECT_BUDGET_MS}ms deadline, took ${elapsedMs}ms`,
164+
);
165+
});
166+
167+
test('a bless refusal in an older runner generation does not end this launch early', async () => {
168+
// The log is append-only across launches, so a bless refusal the previous launch wrote is not
169+
// evidence about this one (#2681). The session's tail reader starts at this generation's offset.
170+
const runnerLogPath = path.join(mkdtempForTestSync('runner-service-hub-stale-'), 'runner.log');
171+
fs.writeFileSync(runnerLogPath, BLESS_LOG);
172+
const generationStartOffset = BLESS_LOG.length;
173+
fs.appendFileSync(
174+
runnerLogPath,
175+
'2026-10-15 10:24:41.112 xcodebuild[9:1] [MT] iOSSimulator: waiting for the simulator to boot\n',
176+
);
177+
const session = {
178+
...sessionWithLaunchLog('', null),
179+
runnerLogPath,
180+
readLogTail: (maxBytes: number) =>
181+
readRunnerLogTail({ logPath: runnerLogPath, startOffset: generationStartOffset }, maxBytes),
182+
};
183+
vi.stubGlobal(
184+
'fetch',
185+
vi.fn(async () => {
186+
throw Object.assign(new Error('connect ECONNREFUSED 127.0.0.1:8100'), {
187+
code: 'ECONNREFUSED',
188+
});
189+
}),
190+
);
191+
192+
await assert.rejects(
193+
() =>
194+
waitForRunner(
195+
iosSimulator,
196+
RUNNER_ENDPOINT_FIXTURE,
197+
{ command: 'snapshot' },
198+
undefined,
199+
300,
200+
session,
201+
),
202+
(error: unknown) => {
203+
// The ordinary connect failure, on the ordinary deadline: nothing named this boot.
204+
assert.equal((error as AppError).details?.reason, 'IOS_RUNNER_CONNECT_TIMEOUT');
205+
return true;
206+
},
207+
);
208+
});
209+
210+
test('a runner that already answered is not re-judged by its launch log', async () => {
211+
// A bless line written during a boot that did serve commands (an Xcode fixed mid-session, say) must
212+
// not refuse a later command on the strength of it.
213+
const fetchSpy = vi.fn(async () => runnerTransportResponse());
214+
vi.stubGlobal('fetch', fetchSpy);
215+
const session = { ...sessionWithLaunchLog(BLESS_LOG, null), state: 'ready' as const };
216+
217+
const response = await waitForRunner(
218+
iosSimulator,
219+
RUNNER_ENDPOINT_FIXTURE,
220+
{ command: 'snapshot' },
221+
undefined,
222+
300,
223+
session,
224+
);
225+
226+
assert.equal(response.status, 200);
227+
assert.equal(fetchSpy.mock.calls.length, 1);
228+
});
229+
128230
test('a still-alive xcodebuild whose log names no service-hub cause keeps the ordinary connect failure', async () => {
129231
vi.stubGlobal(
130232
'fetch',

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

Lines changed: 25 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -208,6 +208,30 @@ export type RunnerDeviceReadinessFailureReason =
208208
export const SIMULATOR_SERVICE_HUB_UNAVAILABLE_REASON: RunnerStartupFailureReason =
209209
'simulator_service_hub_unavailable';
210210

211+
/**
212+
* 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.
217+
*/
218+
const SIMULATOR_SERVICE_HUB_BLESS_MATCH = [
219+
'dtservicehubclient',
220+
'failed to bless service hub',
221+
] as const;
222+
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+
211235
/**
212236
* Names the cause in the message beside the connect-shaped failure the bless refusal produced. The
213237
* reason and hint come from {@link classifyRunnerStartupFailure}; this only folds the cause into the
@@ -441,7 +465,7 @@ export const RUNNER_ERROR_RULES: readonly RunnerErrorRule[] = [
441465
// the same line of the launch output; the domain names the client, the complaint names the bless.
442466
reason: 'simulator_service_hub_bless_refused',
443467
match: {
444-
toolTextLineIncludesAll: ['dtservicehubclient', 'failed to bless service hub'],
468+
toolTextLineIncludesAll: SIMULATOR_SERVICE_HUB_BLESS_MATCH,
445469
},
446470
verdicts: {},
447471
buildFailure: {

‎packages/platform-apple/src/runner/runner-startup-transport.ts‎

Lines changed: 26 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -21,6 +21,7 @@ import {
2121
RUNNER_CACHE_RECOVERY_HINT,
2222
runnerConnectFailureDetails,
2323
shouldRetryRunnerConnectError,
24+
isSimulatorServiceHubLaunchOutput,
2425
SIMULATOR_SERVICE_HUB_UNAVAILABLE_REASON,
2526
simulatorServiceHubFailureMessage,
2627
type RunnerStartupFailureReason,
@@ -41,6 +42,7 @@ export type RunnerConnectionSession = Pick<
4142
| 'readLogTail'
4243
| 'device'
4344
| 'runnerLogPath'
45+
| 'state'
4446
>;
4547
import {
4648
runnerSimulatorSetFailureDetails,
@@ -220,6 +222,7 @@ async function attemptRunnerConnection(params: {
220222

221223
async function ensureRunnerAttemptCanStart(params: {
222224
endpoint: RunnerEndpoint;
225+
route: RunnerCommandRoute;
223226
timeoutMs: number;
224227
logPath?: string;
225228
session?: RunnerConnectionSession;
@@ -238,6 +241,25 @@ async function ensureRunnerAttemptCanStart(params: {
238241
logPath: params.logPath,
239242
});
240243
}
244+
// A launch whose simulator service this macOS refused never serves a command, and its child stays
245+
// alive to the deadline, so without this the request waits out the whole connect budget before
246+
// reaching the classifier that names the cause (#3449). Checked on each attempt while the session
247+
// has yet to answer: once a runner has answered, its log is no longer evidence about a boot that
248+
// demonstrably succeeded. Bounded to the tail an error would quote, read from this generation's
249+
// offset, and no child process is spawned for it.
250+
const session = params.session;
251+
if (session?.state !== 'starting') return;
252+
const launchLogOutput = session.readLogTail?.(RUNNER_EARLY_EXIT_LOG_TAIL_BYTES) ?? '';
253+
if (!isSimulatorServiceHubLaunchOutput(launchLogOutput)) return;
254+
throw buildRunnerConnectError({
255+
device: session.device,
256+
port: params.endpoint.port,
257+
url: params.route.url,
258+
logPath: params.logPath,
259+
lastError: null,
260+
session,
261+
launchLogOutput,
262+
});
241263
}
242264

243265
async function tryPrimaryRunnerRoute(params: {
@@ -446,12 +468,15 @@ function buildRunnerConnectError(params: {
446468
logPath?: string;
447469
lastError: unknown;
448470
session?: RunnerConnectionSession;
471+
/** The launch tail already read for this decision; read here when it is absent. */
472+
launchLogOutput?: string;
449473
}): AppError {
450474
const { device, port, url, logPath, lastError, session } = params;
451475
const message = 'Runner did not accept connection';
452476
const launchLogCause = resolveRunnerLaunchLogCause({
453477
message,
454-
output: session?.readLogTail?.(RUNNER_EARLY_EXIT_LOG_TAIL_BYTES) ?? '',
478+
output:
479+
params.launchLogOutput ?? session?.readLogTail?.(RUNNER_EARLY_EXIT_LOG_TAIL_BYTES) ?? '',
455480
device,
456481
});
457482
const error = new AppError('COMMAND_FAILED', launchLogCause?.message ?? message, {

‎src/commands/schema/cli-help.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -496,7 +496,7 @@ iOS physical-device prerequisites:
496496
If Xcode cannot choose a profile, set AGENT_DEVICE_IOS_PROVISIONING_PROFILE to the profile name/specifier, not a file path.
497497
AGENT_DEVICE_IOS_SIGNING_IDENTITY is optional; omit it unless xcodebuild asks for a specific identity.
498498
The profile/team must allow AGENT_DEVICE_IOS_BUNDLE_ID and <id>.uitests.
499-
A runner startup failure names its class in error details.reason rather than only in prose: signing_no_development_team, signing_provisioning_profile_missing, bundle_identifier_already_registered, signing_unspecified, devtools_security_developer_mode_disabled (the Mac's DevToolsSecurity setting, which says nothing about the device's Developer Mode toggle), simulator_service_hub_unavailable (an Xcode too old for the host macOS: macOS refuses to load its DTServiceHub, so every runner launch fails; select an Xcode that supports this macOS on the daemon host), device_developer_mode_disabled (read from an iPhone's own report before the runner builds, and the only device state that stops a run up front), device_developer_disk_image_unavailable (also read from the device, and published on a startup failure that named no cause of its own, since iOS 17+ mounts the developer disk image on demand during build and launch rather than gating the build), or build_failed_unclassified when nothing proved a cause. The two device reasons are never inferred from tool output or from each other. Branch on details.reason and follow hint; the message is for humans.
499+
A runner startup failure names its class in error details.reason rather than only in prose: signing_no_development_team, signing_provisioning_profile_missing, bundle_identifier_already_registered, signing_unspecified, devtools_security_developer_mode_disabled (the Mac's DevToolsSecurity setting, which says nothing about the device's Developer Mode toggle), simulator_service_hub_unavailable (an Xcode too old for the host macOS: macOS refuses to load its DTServiceHub, so every runner launch fails; the command stops as soon as the refusal reaches runner.log, and selecting an Xcode that supports this macOS on the daemon host is the fix), simulator_set_destination_not_found (a --ios-simulator-device-set simulator the selected Xcode cannot resolve; names the set), device_developer_mode_disabled (read from an iPhone's own report before the runner builds, and the only device state that stops a run up front), device_developer_disk_image_unavailable (also read from the device, and published on a startup failure that named no cause of its own, since iOS 17+ mounts the developer disk image on demand during build and launch rather than gating the build), or build_failed_unclassified when nothing proved a cause. The two device reasons are never inferred from tool output or from each other. Branch on details.reason and follow hint; the message is for humans.
500500
First-run XCTest setup/build can take longer than normal commands; keep the device connected and use --debug to inspect signing/build diagnostics if setup times out.
501501
502502
Android physical-device prerequisites:
Lines changed: 88 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,88 @@
1+
import assert from 'node:assert/strict';
2+
import fs from 'node:fs';
3+
import path from 'node:path';
4+
import { fileURLToPath } from 'node:url';
5+
import { test } from 'vitest';
6+
7+
/**
8+
* `error.details.reason` is a published vocabulary: a client that branches on it treats an
9+
* undocumented member as an unknown value. Nothing but this file connects the union to the two
10+
* surfaces that enumerate it, so a new reason added to the classifier has to be documented in the
11+
* same change. The reason union is the source of truth; the docs are read as text because they carry
12+
* the prose a reader follows, not a machine-readable list.
13+
*/
14+
15+
const repoRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../..');
16+
const classificationPath = path.join(
17+
repoRoot,
18+
'packages/platform-apple/src/runner/runner-error-classification.ts',
19+
);
20+
const installationDocPath = path.join(repoRoot, 'website/docs/docs/installation.md');
21+
const cliHelpPath = path.join(repoRoot, 'src/commands/schema/cli-help.ts');
22+
23+
/** The two reasons the device reports about itself, spread into the startup union. */
24+
const DEVICE_READINESS_MEMBERS = 'RUNNER_DEVICE_READINESS_FAILURE_REASONS';
25+
26+
test('the runner startup reason union is documented in full at both prose surfaces', () => {
27+
const reasons = startupFailureReasons();
28+
29+
for (const { surface, line } of [
30+
{ surface: 'installation.md', line: startupReasonSentence(readFile(installationDocPath)) },
31+
{ surface: 'cli-help.ts', line: startupReasonSentence(readFile(cliHelpPath)) },
32+
]) {
33+
for (const reason of reasons) {
34+
assert.ok(
35+
line.includes(reason),
36+
`${surface} must document the ${reason} reason: the union in ` +
37+
`${path.relative(repoRoot, classificationPath)} publishes it and a client cannot branch on ` +
38+
'a value it was never told exists.',
39+
);
40+
}
41+
}
42+
});
43+
44+
/**
45+
* Every member of `RUNNER_STARTUP_FAILURE_REASONS`, including the ones spread in from the
46+
* device-readiness list. Anything the two lists no longer read as fails rather than silently
47+
* shrinking the set the guard checks.
48+
*/
49+
function startupFailureReasons(): string[] {
50+
const source = readFile(classificationPath);
51+
const reasons: string[] = [];
52+
for (const member of literalMembers(source, 'RUNNER_STARTUP_FAILURE_REASONS')) {
53+
if (!member.startsWith('...')) {
54+
reasons.push(member);
55+
continue;
56+
}
57+
assert.equal(
58+
member,
59+
`...${DEVICE_READINESS_MEMBERS}`,
60+
`unknown spread in RUNNER_STARTUP_FAILURE_REASONS: ${member}`,
61+
);
62+
reasons.push(...literalMembers(source, DEVICE_READINESS_MEMBERS));
63+
}
64+
assert.ok(reasons.length > 0, 'the startup reason union must not read as empty');
65+
return reasons;
66+
}
67+
68+
/** The members of one `export const X = [...] as const;` literal, in source order. */
69+
function literalMembers(source: string, name: string): string[] {
70+
const declaration = new RegExp(`export const ${name} = \\[([\\s\\S]*?)\\] as const`).exec(source);
71+
assert.ok(declaration, `${name} no longer reads as a string-literal union`);
72+
return [...declaration[1]!.matchAll(/'([a-z_]+)'|\.\.\.([A-Z_]+)/g)].map((match) =>
73+
match[1] === undefined ? `...${match[2]}` : match[1]!,
74+
);
75+
}
76+
77+
/** The sentence that enumerates the startup reasons, found on the same line at both surfaces. */
78+
function startupReasonSentence(text: string): string {
79+
const line = text
80+
.split('\n')
81+
.find((candidate) => /error details\.reason|`error\.details\.reason`/.test(candidate));
82+
assert.ok(line, 'no sentence enumerating error.details.reason was found');
83+
return line;
84+
}
85+
86+
function readFile(absolutePath: string): string {
87+
return fs.readFileSync(absolutePath, 'utf8');
88+
}

0 commit comments

Comments
 (0)