@@ -33,6 +33,7 @@ import {
3333 buildIndexMap ,
3434 filterIdentitySet ,
3535} from '../../../replay/target-evidence-tree.ts' ;
36+ import { runWithinWaitDeadline } from './wait-deadline.ts' ;
3637import {
3738 annotationLocalIdentity ,
3839 type TargetAnnotationV1 ,
@@ -578,15 +579,31 @@ async function waitForSelector(
578579 // polling; only the deadline turns this into the fail-closed refusal.
579580 let landmarkMismatch : WaitLandmarkMismatchEvidence | undefined ;
580581 const unreadable = createUnreadablePollTracker ( ) ;
582+ let captureStalled = false ;
581583 while ( now ( runtime ) - start < timeout ) {
582584 // Presence-only poll: skip scroll-hint derivation (#1270), same as waitForFindMatch.
583- const capture = await unreadable . attempt ( ( ) =>
584- captureSelectorSnapshot ( runtime , options , {
585- updateSession : true ,
586- includeHiddenContentHints : false ,
587- ...capturePolicy ,
588- } ) ,
585+ const poll = await runUnreadableWaitPoll (
586+ runtime ,
587+ options ,
588+ unreadable ,
589+ start ,
590+ timeout ,
591+ async ( signal ) =>
592+ await captureSelectorSnapshot (
593+ runtime ,
594+ { ...options , signal } ,
595+ {
596+ updateSession : true ,
597+ includeHiddenContentHints : false ,
598+ ...capturePolicy ,
599+ } ,
600+ ) ,
589601 ) ;
602+ if ( poll . timedOut ) {
603+ captureStalled = true ;
604+ break ;
605+ }
606+ const capture = poll . value ;
590607 if ( capture ) {
591608 const nodes = capture . snapshot . nodes ;
592609 const matchList = listSelectorChainMatches ( nodes , chain , {
@@ -608,6 +625,9 @@ async function waitForSelector(
608625 }
609626 await sleep ( runtime , POLL_INTERVAL_MS ) ;
610627 }
628+ if ( captureStalled ) {
629+ throw waitCaptureStalledError ( `wait timed out for selector: ${ selectorExpression } ` , timeout ) ;
630+ }
611631 if ( landmarkMismatch ) {
612632 throw new AppError (
613633 'COMMAND_FAILED' ,
@@ -628,10 +648,12 @@ async function waitForSelector(
628648 * deadline so persistent breakage keeps its capture diagnosis instead of a
629649 * generic timeout.
630650 */
631- function createUnreadablePollTracker ( ) : {
651+ type UnreadablePollTracker = {
632652 attempt : < T > ( capture : ( ) => Promise < T > ) => Promise < T | undefined > ;
633653 rethrowIfNeverReadable : ( ) => void ;
634- } {
654+ } ;
655+
656+ function createUnreadablePollTracker ( ) : UnreadablePollTracker {
635657 let sawReadableCapture = false ;
636658 let lastUnreadableError : unknown ;
637659 return {
@@ -702,19 +724,64 @@ async function waitForText(
702724 const timeout = timeoutMs ?? DEFAULT_TIMEOUT_MS ;
703725 const start = now ( runtime ) ;
704726 const unreadable = createUnreadablePollTracker ( ) ;
727+ let captureStalled = false ;
705728 while ( now ( runtime ) - start < timeout ) {
706- const found = await unreadable . attempt ( async ( ) =>
707- runtime . backend . findText
708- ? ( await runtime . backend . findText ( toBackendContext ( runtime , options ) , text ) ) . found
709- : await snapshotContainsText ( runtime , options , text ) ,
729+ const poll = await runUnreadableWaitPoll (
730+ runtime ,
731+ options ,
732+ unreadable ,
733+ start ,
734+ timeout ,
735+ async ( signal ) =>
736+ runtime . backend . findText
737+ ? (
738+ await runtime . backend . findText (
739+ toBackendContext ( runtime , { ...options , signal } ) ,
740+ text ,
741+ )
742+ ) . found
743+ : await snapshotContainsText ( runtime , { ...options , signal } , text ) ,
710744 ) ;
745+ if ( poll . timedOut ) {
746+ captureStalled = true ;
747+ break ;
748+ }
749+ const found = poll . value ;
711750 if ( found ) return { kind : 'text' , text, waitedMs : now ( runtime ) - start } ;
712751 await sleep ( runtime , POLL_INTERVAL_MS ) ;
713752 }
753+ if ( captureStalled ) {
754+ throw waitCaptureStalledError ( `wait timed out for text: ${ text } ` , timeout ) ;
755+ }
714756 unreadable . rethrowIfNeverReadable ( ) ;
715757 throw new AppError ( 'COMMAND_FAILED' , `wait timed out for text: ${ text } ` ) ;
716758}
717759
760+ async function runUnreadableWaitPoll < T > (
761+ runtime : AgentDeviceRuntime ,
762+ options : WaitCommandOptions ,
763+ unreadable : UnreadablePollTracker ,
764+ start : number ,
765+ timeoutMs : number ,
766+ capture : ( signal : AbortSignal ) => Promise < T > ,
767+ ) {
768+ return await runWithinWaitDeadline (
769+ runtime ,
770+ options ,
771+ timeoutMs - ( now ( runtime ) - start ) ,
772+ async ( signal ) => await unreadable . attempt ( ( ) => capture ( signal ) ) ,
773+ ) ;
774+ }
775+
776+ function waitCaptureStalledError ( message : string , timeoutMs : number ) : AppError {
777+ return new AppError ( 'COMMAND_FAILED' , message , {
778+ reason : 'wait_capture_stalled' ,
779+ captureStalled : true ,
780+ timeoutMs,
781+ hint : 'A snapshot capture stalled past the wait timeout. Retry, or use screenshot to inspect the current surface.' ,
782+ } ) ;
783+ }
784+
718785async function snapshotContainsText (
719786 runtime : AgentDeviceRuntime ,
720787 options : WaitCommandOptions ,
0 commit comments