fix: report blockers on wait timeout

[thymikee]

Summary

Add compact current-surface diagnostics to wait timeout errors so agents can see likely visible blockers without dumping a full snapshot.

Closes #534.

Details:

• Enrich selector/text wait timeouts with top visible labels and button labels when a compact snapshot is available.
• Preserve the existing timeout response when current-surface inspection fails.
• Touched files: 2. Scope stayed within the snapshot/selector wait command family.

Before:

wait timed out for text: Receipt uploaded
wait timed out for selector: id=receipt-uploaded

After:

wait timed out for text: Receipt uploaded. Current surface: Location permission, Allow location access?, Not now, Continue.
wait timed out for selector: id=receipt-uploaded. Current surface: Location required, Dismiss.

Structured error details also include currentSurface.labels and, when available, currentSurface.buttons.

Validation

• pnpm exec vitest run src/daemon/handlers/__tests__/snapshot-handler.test.ts
• pnpm check:quick
• pnpm check:unit

[github-actions]

PR Preview Action v1.8.1
Preview removed because the pull request was closed.
2026-05-15 12:55 UTC

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: b46010ea0c

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Avoid reusing wait filters for blocker inspection

When a timed-out wait was invoked with selector snapshot filters such as --scope or --depth, this diagnostic snapshot inherits those same filters via ...params.req.flags. In the common blocker case where a permission dialog or modal appears outside the scoped subtree or below the requested depth, inspectCurrentSurface can return no labels/buttons (or a misleading root-only summary), so the new timeout message still fails to report the actual current surface. The post-timeout inspection should take an unscoped, sufficiently broad snapshot instead of carrying over the wait search filters.

Useful? React with 👍 / 👎.