Address agent-friction issues from real usage analysis (#30, #31, #32, #33)

[detrin]

Fixes derived from analyzing 5,505 real brow calls across 11 agent projects. Each fix targets a quantified friction point.

Closes

• Closes fix: accept '[N]' as a ref in click/fill/select (snapshot output teaches wrong input) #30 — [N] as ref
• Closes fix: session profile lock has no recovery — 117 'already in use' errors in the wild #31 — session reclaim
• Closes fix: eval footguns — auto-await top-level coroutines, clearer errors #32 — eval footguns
• Closes fix: weak auto-settle forces manual sleeps (1,947 'sleep N' calls around brow) #33 — auto-settle

Changes

#30 [N] ref-as-selector (25 failed calls)

_resolve_selector now coerces a bare [N]/N selector to [data-brow-ref="N"]. Agents copy the snapshot token [1] and click "[1]" just works instead of SyntaxError: '[1]' is not a valid selector.

#31 session profile lock (117 "already in use" errors)

• session new --reclaim closes the stale holder and takes over the profile.
• Conflict message now says: ... Retry with reclaim, or run: brow session delete N.

#32 eval footguns (26 'coroutine' errors)

• text(sel) / texts(sel) async helpers in the eval namespace for the common "just get the text" case.
• Un-awaited-coroutine errors now append: "page methods are async; did you forget 'await'?".

#33 weak auto-settle (1,947 manual sleep N)

• navigate --wait domcontentloaded|load|networkidle (capped at 10s). Lets agents wait for SPA/network settle instead of guessing sleeps.

Not in this PR

#29 (brow read content extraction) — the biggest finding (1,241 html + 1,173 eval calls bypassing snapshot) is a design feature, deferred to its own PR.

Verification

• 100 tests pass (added: bracket-ref click, networkidle navigate, eval text() helper, coroutine hint, profile conflict + reclaim).
• ruff clean.
• SKILL.md + CHANGELOG updated.

🤖 Generated with Claude Code