1- import {
2- AppError ,
3- createRequestCanceledError ,
4- isRequestCanceledError ,
5- } from '@agent-device/kernel/errors' ;
1+ import { AppError , createRequestCanceledError } from '@agent-device/kernel/errors' ;
62import {
73 withKeyedLock ,
84 Deadline ,
@@ -39,7 +35,6 @@ import {
3935 decodeRunnerResponseBody ,
4036 isRunnerResponseOk ,
4137 readRunnerResponseData ,
42- resolveRunnerStartupSignal ,
4338 withRunnerCommandId ,
4439 type RunnerCommand ,
4540} from './runner-contract.ts' ;
@@ -96,6 +91,7 @@ import {
9691} from './runner-session-types.ts' ;
9792import { launchRunnerProcess , type LaunchedRunnerProcess } from './runner-process-launch.ts' ;
9893import { isSameRunnerSimulator } from './runner-device-set.ts' ;
94+ import type { RunnerStartBudget } from './runner-start-budget.ts' ;
9995
10096export type { RunnerSession } from './runner-session-types.ts' ;
10197
@@ -134,33 +130,6 @@ function withRunnerSessionLock<T>(deviceId: string, task: () => Promise<T>): Pro
134130 return withKeyedLock ( runnerSessionLocks , deviceId , task ) ;
135131}
136132
137- /**
138- * What a runner start may spend when its caller sets no `startupTimeoutMs`: the reuse probe,
139- * adoption, boot, device readiness, the xctestrun build and the launch, on one clock the start owns
140- * (#2894). Sized for a cold build: `prepare` defaults to 240 s for the same work plus its health
141- * check (`PREPARE_STARTUP_BUDGET_MS`), the iOS CI lane gives a cold `prepare` on a shared macOS
142- * runner 420 s (`AGENT_DEVICE_IOS_PREPARE_TIMEOUT_MS`), and a daemon queued on another process's
143- * build of the same artifact already gives up after 10 minutes
144- * (`RUNNER_XCTESTRUN_CACHE_LOCK_TIMEOUT_MS`). The two ceilings agree, so a start never waits on a
145- * peer's build longer than it would spend on its own.
146- */
147- export const DEFAULT_RUNNER_START_BUDGET_MS = 10 * 60_000 ;
148-
149- /**
150- * The budget one runner start spends, with the clock that enforces it. The abort fires when the
151- * deadline is spent, so every step that takes the signal (the xctestrun build and the launch kill
152- * their process tree through exec, the probes stop retrying) ends on the same clock the deadline
153- * reads. `close` retires the timer once the start has settled: a registered session is bounded by
154- * its {@link RunnerSession.launchDeadline} from then on, never by this abort.
155- */
156- type RunnerStartBudget = Readonly < {
157- phase : RunnerPhaseBudget ;
158- timeoutMs : number ;
159- explicit : boolean ;
160- exhausted : AbortSignal ;
161- close : ( ) => void ;
162- } > ;
163-
164133export async function ensureRunnerSession (
165134 device : DeviceInfo ,
166135 options : RunnerSessionOptions ,
@@ -169,6 +138,7 @@ export async function ensureRunnerSession(
169138 // from a retained-after-close runner no longer applies.
170139 cancelIosRunnerIdleStop ( device . id ) ;
171140 const start = withRunnerSessionLock ( device . id , async ( ) => {
141+ const { openRunnerStartBudget } = await import ( './runner-start-budget.ts' ) ;
172142 // One budget for the whole start, opened once the lock is held so a start queued behind
173143 // another does not spend its clock waiting: the reuse check's toolchain probes, adoption and
174144 // the startup itself all read it. The request's cancellation rides with it, so a client
@@ -195,94 +165,10 @@ export async function ensureRunnerSession(
195165 budget . close ( ) ;
196166 }
197167 } ) ;
168+ const { raceRunnerStartAgainstCaller } = await import ( './runner-start-budget.ts' ) ;
198169 return await raceRunnerStartAgainstCaller ( start , options . signal ) ;
199170}
200171
201- /**
202- * Opens the start's budget from `startupTimeoutMs`, or {@link DEFAULT_RUNNER_START_BUDGET_MS}
203- * when the caller sets none. The startup signal (a cancelled request, never a caller's deadline)
204- * and the budget's own expiry abort the same signal.
205- */
206- function openRunnerStartBudget ( options : RunnerSessionOptions ) : RunnerStartBudget {
207- const explicitTimeoutMs = normalizeRunnerStartupTimeoutMs ( options . startupTimeoutMs ) ;
208- const timeoutMs = explicitTimeoutMs ?? DEFAULT_RUNNER_START_BUDGET_MS ;
209- const exhausted = new AbortController ( ) ;
210- const timer = setTimeout ( ( ) => {
211- exhausted . abort ( runnerStartBudgetExhaustedError ( timeoutMs , explicitTimeoutMs !== undefined ) ) ;
212- } , timeoutMs ) ;
213- timer . unref ?.( ) ;
214- const startupSignal = resolveRunnerStartupSignal ( options ) ;
215- const signal = startupSignal
216- ? AbortSignal . any ( [ startupSignal , exhausted . signal ] )
217- : exhausted . signal ;
218- return {
219- phase : createRunnerPhaseBudget ( timeoutMs , signal ) ,
220- timeoutMs,
221- explicit : explicitTimeoutMs !== undefined ,
222- exhausted : exhausted . signal ,
223- close : ( ) => clearTimeout ( timer ) ,
224- } ;
225- }
226-
227- /** Says the start's own budget ran out, whichever step it was in; the next request starts over. */
228- function runnerStartBudgetExhaustedError ( timeoutMs : number , explicit : boolean ) : AppError {
229- return new AppError (
230- 'COMMAND_FAILED' ,
231- `Apple runner start exceeded its ${ explicit ? 'startup timeout' : 'default start budget' } of ${ timeoutMs } ms` ,
232- {
233- reason : 'runner_start_budget_exhausted' ,
234- timeoutMs,
235- retriable : true ,
236- hint : explicit
237- ? 'Raise the startup timeout, or run `prepare ios-runner` first so the runner is built before it is needed.'
238- : 'Run `prepare ios-runner --timeout <ms>` so the cold build has a budget of your choosing; the session runner.log names the step that stalled.' ,
239- } ,
240- ) ;
241- }
242-
243- /**
244- * The start runs detached under the session lock; the caller only waits for it as long as its own
245- * signal allows. A caller whose deadline lands during a cold xctestrun build leaves on time, the
246- * build keeps going under the lock, and the next request for the device queues behind it and joins
247- * the session it registers (#2894). Whatever the abort reason, the caller sees the same cancelled
248- * request it would have seen from any later step; a cancelled request's abort also reaches the
249- * start through its own startup signal, so nothing here decides whether the start survives. A
250- * start that fails after its caller left has nobody to report to, so its failure is logged here.
251- */
252- async function raceRunnerStartAgainstCaller (
253- start : Promise < RunnerSession > ,
254- signal : AbortSignal | undefined ,
255- ) : Promise < RunnerSession > {
256- if ( ! signal ) return await start ;
257- return await new Promise < RunnerSession > ( ( resolve , reject ) => {
258- const abort = ( ) => {
259- reject ( createRequestCanceledError ( undefined , signal . reason ) ) ;
260- start . catch ( emitDetachedRunnerStartFailed ) ;
261- } ;
262- if ( signal . aborted ) {
263- abort ( ) ;
264- } else {
265- signal . addEventListener ( 'abort' , abort , { once : true } ) ;
266- }
267- start . then ( resolve , reject ) . finally ( ( ) => signal . removeEventListener ( 'abort' , abort ) ) ;
268- } ) ;
269- }
270-
271- /** A cancelled request killed its start on purpose; any other failure of a start nobody awaits is news. */
272- function emitDetachedRunnerStartFailed ( error : unknown ) : void {
273- if ( isRequestCanceledError ( error ) ) return ;
274- const appErr = error instanceof AppError ? error : undefined ;
275- emitDiagnostic ( {
276- level : 'warn' ,
277- phase : 'ios_runner_detached_start_failed' ,
278- data : {
279- code : appErr ?. code ,
280- reason : appErr ?. details ?. reason ,
281- error : error instanceof Error ? error . message : String ( error ) ,
282- } ,
283- } ) ;
284- }
285-
286172/** How long the device-readiness probe may take, bounded by the startup budget it runs inside. */
287173const RUNNER_DEVICE_READINESS_BUDGET_MS = 10_000 ;
288174
0 commit comments