Annotation index lifecycle unclear — LLMs waste retries on stale annotations

[rafiki270]

Problem

LLMs use screenshot-annotated to get numbered element annotations, then use click-annotation or fill-annotation with those indices. But annotations expire silently when the page changes, and the LLM doesn't know:

• How long annotations are valid
• What invalidates them (any navigation? DOM mutation? scroll?)
• Whether there's a way to check if annotations are still valid

The ANNOTATION_EXPIRED error code exists but only appears after the LLM has already tried to use a stale index.

Proposal

1. Include annotation TTL/validity info in the screenshot-annotated response:

   { "annotations": [...], "validUntil": "next_navigation", "sessionId": "abc123" }

2. Add an annotations-valid endpoint to check without taking a new screenshot

3. Document annotation lifecycle in --llm-help metadata for screenshot-annotated, click-annotation, and fill-annotation

4. Consider auto-invalidation warning: if the page URL or DOM hash changed since the last annotation, include a warning in the next command's response

[rafiki270]

Fixed: annotation session lifecycle with URL-based expiry. screenshot-annotated now generates sessionId and tracks page URL. click-annotation/fill-annotation validate URL match and return ANNOTATION_EXPIRED if page changed. Router now registers fallback stubs for unsupported methods.