@@ -30,6 +30,7 @@ import { runReplayScriptFile } from '../session-replay-runtime.ts';
3030import { SessionStore } from '../../session-store.ts' ;
3131import type { DaemonRequest } from '../../types.ts' ;
3232import { dispatchCommand } from '../../../core/dispatch.ts' ;
33+ import { AppError } from '../../../kernel/errors.ts' ;
3334import { makeIosSession } from '../../../__tests__/test-utils/session-factories.ts' ;
3435
3536const mockDispatchCommand = vi . mocked ( dispatchCommand ) ;
@@ -497,28 +498,42 @@ test('a target-binding divergence carries a real computed resume (step 5 wiring,
497498} ) ;
498499
499500// #1385: a step-2 press right after `open --relaunch` can capture while the
500- // app is still launching/mounting — the pre-dispatch verification capture
501- // throws (Android's "insufficient foreground app content" surfaces as a
502- // thrown capture failure) or returns sparse on the first attempt(s), then
503- // recovers once the app finishes mounting. The bounded retry in
504- // `captureDivergenceObservation` (`retryLaunchRace`) must ride that out
505- // instead of failing closed on the first unlucky capture.
506- test ( 'a transient pre-dispatch capture failure right after launch recovers within the bounded retry, and the action still dispatches' , async ( ) => {
501+ // app is still launching/mounting. The bounded retry in
502+ // `captureDivergenceObservation` (`retryLaunchRace`) only rides out a
503+ // content-quality verdict — the same `retriable: true` signal Android's
504+ // helper capture path already emits for a content-poor/system-window-only
505+ // rejection (`rejectAndroidHelperContentUnavailable`) — not a mechanism
506+ // failure (helper artifact missing, device offline), which must still fail
507+ // fast. `throwRetriableCaptureFailure`/`throwPermanentCaptureFailure` below
508+ // build the two shapes.
509+ function throwRetriableCaptureFailure ( ) : never {
510+ throw new AppError (
511+ 'COMMAND_FAILED' ,
512+ 'Android snapshot helper returned insufficient foreground app content' ,
513+ { retriable : true } ,
514+ ) ;
515+ }
516+
517+ function throwPermanentCaptureFailure ( ) : never {
518+ throw new AppError (
519+ 'COMMAND_FAILED' ,
520+ 'Android snapshot helper is unavailable: the bundled helper artifact was not found' ,
521+ ) ;
522+ }
523+
524+ test ( 'a transient content-quality capture failure right after launch recovers within the bounded retry, and the action still dispatches' , async ( ) => {
507525 const root = fs . mkdtempSync (
508526 path . join ( os . tmpdir ( ) , 'agent-device-replay-target-verify-launch-race-recover-' ) ,
509527 ) ;
510528 const { sessionStore, sessionName } = setupSession ( root ) ;
511529 const filePath = writeReplayFile ( root , [ SAVE_ANNOTATION , 'click id="save"' ] ) ;
512530
513- // First two captures fail closed (mirrors a mid-launch/mid-mount capture);
514- // the third lands after the app settles and finds the recorded target.
531+ // First two captures fail closed with a content-quality (retriable) verdict
532+ // (mirrors a mid-launch/mid-mount capture); the third lands after the app
533+ // settles and finds the recorded target.
515534 mockDispatchCommand
516- . mockImplementationOnce ( async ( ) => {
517- throw new Error ( 'Android snapshot helper returned insufficient foreground app content' ) ;
518- } )
519- . mockImplementationOnce ( async ( ) => {
520- throw new Error ( 'Android snapshot helper returned insufficient foreground app content' ) ;
521- } )
535+ . mockImplementationOnce ( async ( ) => throwRetriableCaptureFailure ( ) )
536+ . mockImplementationOnce ( async ( ) => throwRetriableCaptureFailure ( ) )
522537 . mockResolvedValue ( {
523538 nodes : [
524539 {
@@ -551,16 +566,14 @@ test('a transient pre-dispatch capture failure right after launch recovers withi
551566 expect ( mockDispatchCommand ) . toHaveBeenCalledTimes ( 3 ) ;
552567} ) ;
553568
554- test ( 'a pre-dispatch capture failure that never recovers still fails closed as identity-unverifiable once the bounded retry is exhausted' , async ( ) => {
569+ test ( 'a content-quality capture failure that never recovers still fails closed as identity-unverifiable once the bounded retry is exhausted' , async ( ) => {
555570 const root = fs . mkdtempSync (
556571 path . join ( os . tmpdir ( ) , 'agent-device-replay-target-verify-launch-race-exhausted-' ) ,
557572 ) ;
558573 const { sessionStore, sessionName } = setupSession ( root ) ;
559574 const filePath = writeReplayFile ( root , [ SAVE_ANNOTATION , 'click id="save"' ] ) ;
560575
561- mockDispatchCommand . mockImplementation ( async ( ) => {
562- throw new Error ( 'Android snapshot helper returned insufficient foreground app content' ) ;
563- } ) ;
576+ mockDispatchCommand . mockImplementation ( async ( ) => throwRetriableCaptureFailure ( ) ) ;
564577
565578 const invoked : DaemonRequest [ ] = [ ] ;
566579 const response = await runReplayScriptFile ( {
@@ -587,6 +600,38 @@ test('a pre-dispatch capture failure that never recovers still fails closed as i
587600 expect ( mockDispatchCommand . mock . calls . length ) . toBeGreaterThan ( 1 ) ;
588601} ) ;
589602
603+ test ( 'a permanent (non-content-quality) capture failure fails fast without retrying' , async ( ) => {
604+ const root = fs . mkdtempSync (
605+ path . join ( os . tmpdir ( ) , 'agent-device-replay-target-verify-launch-race-permanent-' ) ,
606+ ) ;
607+ const { sessionStore, sessionName } = setupSession ( root ) ;
608+ const filePath = writeReplayFile ( root , [ SAVE_ANNOTATION , 'click id="save"' ] ) ;
609+
610+ // A missing helper artifact is not something a launch-race retry can fix —
611+ // it never carries `retriable: true`, so the capture must fail on the
612+ // FIRST attempt, not spend the retry budget on a foregone conclusion.
613+ mockDispatchCommand . mockImplementation ( async ( ) => throwPermanentCaptureFailure ( ) ) ;
614+
615+ const invoked : DaemonRequest [ ] = [ ] ;
616+ const response = await runReplayScriptFile ( {
617+ req : baseReq ( { positionals : [ filePath ] } ) ,
618+ sessionName,
619+ logPath : path . join ( root , 'daemon.log' ) ,
620+ sessionStore,
621+ invoke : async ( req ) => {
622+ invoked . push ( req ) ;
623+ return { ok : true , data : { } } ;
624+ } ,
625+ } ) ;
626+
627+ expect ( invoked . length ) . toBe ( 0 ) ;
628+ expect ( response . ok ) . toBe ( false ) ;
629+ if ( response . ok ) return ;
630+ const divergence = response . error . details ?. divergence as Record < string , unknown > ;
631+ expect ( divergence . kind ) . toBe ( 'identity-unverifiable' ) ;
632+ expect ( mockDispatchCommand ) . toHaveBeenCalledTimes ( 1 ) ;
633+ } ) ;
634+
590635// ---------------------------------------------------------------------------
591636// #1349: wait's post-resolution landmark verification. An annotated selector
592637// wait must NEVER enter the generic pre-dispatch resolution path — polling is
0 commit comments