> ## Documentation Index
> Fetch the complete documentation index at: https://docs.reticle.sh/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Reticle is a dev-only, localhost-only verification layer for AI coding agents. It reads program truth (network, state, console, routing, animations, framework state) from inside a running web app and returns a deterministic verdict with evidence. It is not a screenshot tool and not a browser automation library.
> Only `reticle_act_and_wait` and `reticle_assert` produce a verdict. Every other tool moves or reads the app and proves nothing. A drive that ends without one of those two has no result, however many tools it used.
> A verdict of `verified: "unknown"` is not a pass. It means Reticle drove the app and could not tell what happened. Report it as unknown; never weaken a check to make it pass.
> Package names are scoped `@reticlehq/*` and the CLI is `reticle`. Install with `npx reticle init`. The complete tool surface is on the `/usage` page; `/agent-cheatsheet` is the one-screen version.

# reticle_wait_for

> Block until a predicate holds. Or return immediately if it is already true in the recent buffer.

`reticle_wait_for` takes the same predicate grammar as [`reticle_act_and_wait`](/tools-act-and-wait), without the action. Use it when the thing you are waiting for was triggered by something other than your own click. A timer, a websocket push, a background refresh.

## Example

```json theme={"dark"}
{
  "predicate": { "kind": "text", "value": "Invalid email or password" },
  "timeout_ms": 3000
}
```

Real response:

```json theme={"dark"}
{
  "pass": true,
  "evidence": [
    {
      "ref": "e104",
      "role": "alert",
      "name": "Invalid email or password",
      "visible": false,
      "source": "src/components/Login.tsx:72",
      "states": ["present", "hidden", "enabled"]
    }
  ]
}
```

The evidence is the element itself, with the file and line that rendered it.

<Note>
  Look at `visible: false` and `states: ["present", "hidden", "enabled"]`. The alert exists in the
  DOM and is not visible. `wait_for` on a `text` predicate matches presence, if you need it on
  screen, that is a different question, and [`reticle_inspect`](/tools-inspect) answers it.
</Note>

## It checks the buffer first

`wait_for` does not always wait. If the predicate is already satisfied in the recent event buffer, it returns immediately. This means you can act, then wait, without racing. The event that happened while you were composing the second call is not lost.

## Arguments

| Argument                 | What it does                                                            |
| ------------------------ | ----------------------------------------------------------------------- |
| `predicate` (or `until`) | `{ kind, ...fields }`, see the [predicate grammar](/tools-act-and-wait) |
| `timeout_ms`             | Maximum wait                                                            |
| `since`                  | Cursor from a prior act, to scope the wait                              |

## Prefer `act_and_wait` when you caused it

If your own action is supposed to trigger the thing, put the predicate in the action:

```json theme={"dark"}
{ "ref": "e103", "action": "click", "until": { "kind": "signal", "name": "auth:granted" } }
```

One call instead of two, no gap for an event to slip through, and. The part that matters. The expectation is recorded *before* the action rather than chosen after it.

Save `wait_for` for consequences you did not cause.