88 isRequestCanceledError ,
99} from '@agent-device/kernel/errors' ;
1010import {
11- coldToolchainProbeTimeoutMs ,
1211 createTtlMemo ,
1312 Deadline ,
1413 isCommandTimeoutError ,
@@ -19,6 +18,7 @@ import {
1918 type TtlMemo ,
2019} from './host.ts' ;
2120import {
21+ COLD_TOOLCHAIN_PROBE_TIMEOUT_MS ,
2222 resolveRunnerBuildDestinationFamily ,
2323 resolveRunnerDerivedBaseName ,
2424 resolveRunnerPlatformName ,
@@ -33,13 +33,9 @@ const RUNNER_CACHE_SCHEMA_VERSION = 2;
3333const RUNNER_CACHE_METADATA_VALUE_MAX_LENGTH = 300 ;
3434
3535/**
36- * Ceiling on the wall clock the whole toolchain fingerprint may spend, across
37- * all three probes and their retries, when the owning phase carries no shorter
38- * budget. Sized for the one cold-start stall the retry exists for -- a single
39- * stalled probe (up to the host's `coldToolchainProbeTimeoutMs()`) plus its
40- * now-warm retry and the two remaining probes -- not for three independently
41- * stalling tools, which is why the per-call timeout alone is not the bound
42- * (#2422).
36+ * Ceiling on the wall clock the whole toolchain fingerprint may spend, across all three
37+ * probes and their retries, when the owning phase carries no shorter budget: one stalled
38+ * probe, its warm retry, and the two probes still to run (#2422).
4339 */
4440const TOOLCHAIN_FINGERPRINT_BUDGET_MS = 45_000 ;
4541const TOOLCHAIN_PROBE_MAX_BUFFER = 128 * 1024 ;
@@ -71,25 +67,17 @@ type ToolchainProbeFailure = {
7167} ;
7268
7369/**
74- * The one clock a runner phase spends, for a step whose budget is `timeoutMs`;
75- * `undefined` for a caller that carries no budget at all (background and
76- * preflight surfaces). The cache decision's blocking toolchain probes and the
77- * step the phase exists for (an `xcodebuild` build, a runner startup) both read
78- * it, so what the probes spend is time the step no longer has. Create it once
79- * per phase and read the rest with {@link requireRunnerPhaseRemainingMs}; a
80- * step that hands the probes a timeout and then hands itself the same number
81- * again spends the phase's budget twice (#2422).
70+ * The one clock a runner phase spends, created once per phase and read with
71+ * {@link requireRunnerPhaseRemainingMs}; `undefined` for a caller carrying no budget.
8272 */
8373export function createRunnerPhaseDeadline ( timeoutMs : number | undefined ) : Deadline | undefined {
8474 if ( timeoutMs === undefined || ! Number . isFinite ( timeoutMs ) ) return undefined ;
8575 return Deadline . fromTimeoutMs ( Math . max ( 0 , timeoutMs ) ) ;
8676}
8777
8878/**
89- * What the phase has left for its next step, or `fallbackTimeoutMs` when it
90- * carries no deadline. Throws instead of returning zero: a step reached with
91- * nothing left must fail before it spawns anything, not start a process it
92- * would have to kill immediately.
79+ * What the phase has left for its next step, or `fallbackTimeoutMs` when it carries no
80+ * deadline. Throws rather than returning zero, so a spent phase fails before it spawns.
9381 */
9482export function requireRunnerPhaseRemainingMs (
9583 deadline : Deadline | undefined ,
@@ -102,12 +90,7 @@ export function requireRunnerPhaseRemainingMs(
10290 return remainingMs ;
10391}
10492
105- /**
106- * The one error a runner phase raises when a step is reached with nothing left
107- * to spend, whether that step is an `xcodebuild` build, a runner startup, or a
108- * toolchain probe. It says the budget ran out, not that the thing it would have
109- * run is broken.
110- */
93+ /** Says the phase budget ran out, not that the step it would have run is broken. */
11194function runnerPhaseBudgetExhaustedError ( phase : string ) : AppError {
11295 return new AppError ( 'COMMAND_FAILED' , 'The Apple runner budget ran out before this step began' , {
11396 phase,
@@ -117,17 +100,8 @@ function runnerPhaseBudgetExhaustedError(phase: string): AppError {
117100}
118101
119102/**
120- * What the phase that wants a runner cache decision has left to spend on it.
121- * The decision blocks the calling request on up to three synchronous `spawnSync`
122- * probes, so the phase's own deadline and cancellation must reach them: an
123- * exhausted budget fails the decision instead of starting another 30 second
124- * probe, and a canceled request surfaces the cancellation rather than
125- * retrying (#2422). A caller with neither still gets
126- * {@link TOOLCHAIN_FINGERPRINT_BUDGET_MS} as the ceiling.
127- *
128- * `spawnSync` cannot be interrupted once it has started, so cancellation is
129- * observed between attempts; the per-attempt cap is what bounds how long that
130- * takes.
103+ * What the phase that wants a runner cache decision has left to spend on it. A caller
104+ * with neither field still gets {@link TOOLCHAIN_FINGERPRINT_BUDGET_MS} as the ceiling.
131105 */
132106export type RunnerCacheProbeBudget = {
133107 /** The owning phase's clock, shared with whatever the phase does next. */
@@ -137,9 +111,11 @@ export type RunnerCacheProbeBudget = {
137111} ;
138112
139113/**
140- * The remaining-time and cancellation view the probes consult. One is created
141- * per fingerprint read, so the three probes and their retries share -- and
142- * together cannot exceed -- a single budget.
114+ * The remaining-time and cancellation view the probes consult: one per fingerprint read,
115+ * so the three probes and their retries share a single budget.
116+ *
117+ * `spawnSync` cannot be interrupted once it has started, so cancellation is observed
118+ * between attempts; the per-attempt cap is what bounds how long that takes.
143119 */
144120type ToolchainProbeClock = {
145121 /** Milliseconds the next attempt may block for; 0 once the budget is spent. */
@@ -152,10 +128,6 @@ function createToolchainProbeClock(
152128 budget : RunnerCacheProbeBudget | undefined ,
153129) : ToolchainProbeClock {
154130 const phaseDeadline = budget ?. deadline ;
155- // The fingerprint's own deadline, opened at whichever of the two ceilings is
156- // nearer: the phase's remainder, or the fingerprint budget for a caller with
157- // no phase clock (or a generous one). Both are wall-clock, so the step after
158- // the probes still sees the time they spent.
159131 const deadline = Deadline . fromTimeoutMs (
160132 Math . min (
161133 TOOLCHAIN_FINGERPRINT_BUDGET_MS ,
@@ -164,7 +136,7 @@ function createToolchainProbeClock(
164136 ) ;
165137 return {
166138 attemptTimeoutMs : ( ) =>
167- Math . min ( coldToolchainProbeTimeoutMs ( ) , Math . floor ( deadline . remainingMs ( ) ) ) ,
139+ Math . min ( COLD_TOOLCHAIN_PROBE_TIMEOUT_MS , Math . floor ( deadline . remainingMs ( ) ) ) ,
168140 throwIfCanceled : ( ) => {
169141 if ( budget ?. signal ?. aborted ) {
170142 throw createRequestCanceledError ( { phase : 'apple_toolchain_probe' } ) ;
@@ -279,18 +251,14 @@ function toolchainFingerprintCache(): TtlMemo<string, RunnerToolchainFingerprint
279251}
280252
281253/**
282- * The toolchain half of the cache key, or a failure. A probe that timed out or
283- * could not be read has no value to compare or persist, and the same
284- * fingerprint also names the derived-data directory, so an unreadable
285- * toolchain fails the cache decision instead of standing in for one.
254+ * The toolchain half of the cache key. It also names the derived-data directory, so an
255+ * unreadable toolchain fails the cache decision instead of standing in for one.
286256 */
287257function requireRunnerToolchainFingerprint (
288258 sdkName : string ,
289259 budget : RunnerCacheProbeBudget | undefined ,
290260) : RunnerToolchainFingerprint {
291- // Checked before the cache, not just before the probes: a canceled request
292- // must surface as canceled even on a cache hit, or adoption reads a stale
293- // "success" and goes on to probe uptime and write the lease (#2422).
261+ // Before the cache, not just before the probes: a hit must not hide a cancellation.
294262 const clock = createToolchainProbeClock ( budget ) ;
295263 clock . throwIfCanceled ( ) ;
296264 const cached = toolchainFingerprintCache ( ) . get ( sdkName ) ;
@@ -359,12 +327,7 @@ function runToolchainProbe(
359327 try {
360328 output = runToolchainProbeCommand ( cmd , args , clock ) ;
361329 } catch ( error ) {
362- // A canceled request and a spent budget are the caller's own errors to
363- // see, not an unreadable toolchain: only what's left becomes a probe
364- // failure. Checked again here (not just in attemptToolchainProbe) because
365- // the request can abort while this exec is in flight, after its own guard
366- // already passed -- including on the last probe, where there is no next
367- // attempt left to catch it.
330+ // A cancellation or a spent budget is the caller's error, not an unreadable toolchain.
368331 clock . throwIfCanceled ( ) ;
369332 if ( isRequestCanceledError ( error ) || isRunnerPhaseBudgetExhaustedError ( error ) ) throw error ;
370333 return probeFailure ( probe , 'probe_error' , error instanceof Error ? error . message : `${ error } ` ) ;
@@ -381,17 +344,9 @@ function runToolchainProbe(
381344}
382345
383346/**
384- * Runs one toolchain probe, retrying exactly once if the attempt timed out and
385- * the shared budget still has room. Apple's syspolicyd signature scan blocks
386- * the first `xcodebuild`/`xcrun` exec after a fresh host boots (see
387- * `COLD_TOOLCHAIN_PROBE_TIMEOUT_MS` in `@agent-device/host-kit/command`, which
388- * reaches this file through the host port); the immediate next exec of the same
389- * tool is instant, so the retry recovers without widening the per-call budget. Only the
390- * exec layer's structured timeout is retried -- a tool that failed on its own
391- * and merely said "timed out" in its output is not this stall. The retry calls
392- * the same guarded attempt below, so a request canceled or a budget spent
393- * between attempts is caught there rather than trusted from before the first
394- * one.
347+ * Retries exactly once, and only the exec layer's structured timeout: the stall
348+ * {@link COLD_TOOLCHAIN_PROBE_TIMEOUT_MS} names clears on the next exec of the same tool,
349+ * while a tool that failed on its own and said "timed out" in its output is not it.
395350 */
396351function runToolchainProbeCommand (
397352 cmd : string ,
@@ -406,7 +361,7 @@ function runToolchainProbeCommand(
406361 }
407362}
408363
409- /** The one guard site for a toolchain probe attempt : cancellation and a spent budget both throw here, before anything execs . */
364+ /** The one guard site: cancellation and a spent budget both throw here, before any exec . */
410365function attemptToolchainProbe (
411366 cmd : string ,
412367 args : string [ ] ,
0 commit comments