wrangle 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: c71a3ad462a532ec7f6ddea4621ff5620bfde1085cbdbcb5ec0f04995b2707e3
+  data.tar.gz: de242cf8fa5fb7b3c21c03af57d8f8287db282c487fabc20b61f52459756d113
+SHA512:
+  metadata.gz: f295f56bb4e7553dcac794b08ef3d63295f57a2f18922a6fc1d7142dfde7ece183f0971340db080d7a87ce55fb671ef8c431a8e57cd0fd930d0c710a0c051c5f
+  data.tar.gz: e4d1eaffa60d2360f513aaf20f2a4a97255bc387e24ff3e1e563a1d2c189912c37eba1fb022e25dd4931540a37b8f6f9a74c5fdd6d96361f1d8ce9700b5b145c

data/CHANGELOG.md

@@ -0,0 +1,87 @@
+# Changelog
+
+## [0.1.0] - 2026-09-18
+
+- `wrangle run --goal "..." --execute`: a decision loop driven by Jev, a typed-choice model that
+  picks one of the actions Wrangle observed. It never writes text — `--literal LABEL=VALUE` supplies
+  it, and a fill with no literal stops and asks.
+- `--plan GOAL` (repeatable): ordered sub-goals advanced internally on DONE, so a whole form is one
+  command instead of one agent turn per click. Measured on Google Flights: 29 steps in ~14s, against
+  ten turns and 129s hand-stepping the same task.
+- A confidence floor (`--min-confidence`, default `0.5`) that looks again once before handing back,
+  because a page half-rendered when the model looked reads as ambiguity. `DONE` and `BLOCKED` are
+  held to it too — an uncertain `DONE` still advances a plan, an uncertain `BLOCKED` must earn its
+  handoff, since being wrong about them costs very different amounts.
+- `--side left|right|top|bottom` parks the window on half a display.
+- `--backend mcp` drives `safaridriver --mcp` instead of Apple Events: ~3ms per action against
+  ~120ms, behind ~4s of startup, so it only pays off past roughly 28 actions. Experimental — its
+  automation tab is backgrounded, and menus animated on `requestAnimationFrame` do not respond.
+- `BLOCKED` is held to its own floor (0.6) that `--min-confidence` can raise but not lower, and a
+  weak one gets two further looks with a widening pause before it is believed. A control that has
+  not rendered yet is not a dead end, and lowering the floor to help an underconfident click should
+  not make it easier to abandon the run.
+- Every request carries a verification question — is this goal's outcome visible on the page? —
+  answered independently of the one choosing actions, and read only to dispute a `DONE`. A confident
+  disagreement keeps the leg working; an unsure one is ignored; one that survives three widening
+  pauses hands back. `DONE` is the model reporting on its own work and it is optimistic: a plan
+  reported success with a requested filter never applied.
+- `UNPROVEN` in the transcript marks a claim that did not check out, and does not spend the budget.
+- A dispute only ends a run when the leg it disputes has done nothing. A leg that acted is taken at
+  its word once it has looked again: the verifier reads one snapshot, the actor knows what it did,
+  and abandoning the remaining legs is the more expensive way to be wrong.
+- A leg that has not acted yet cannot report `BLOCKED` without confirming it, however sure it is.
+  A leg starts the instant the last one ends, so it often looks at a document that is still loading,
+  and a half-loaded page does not read as ambiguous — it reads as definite, and reads surer the
+  second time. Up to three further looks, widening to 2.5s.
+- A second look appears in the transcript as `RELOOK` rather than being silently discarded.
+- A `select` is no longer hit-tested before it runs. Styled dropdowns hide the native control under
+  an overlay, which made Amazon's sort permanently unactionable; a select is driven by assigning
+  value and dispatching input/change, so nothing depends on it being the topmost element.
+- A blocked action says which of the four reasons stopped it — gone, read-only, scrolled out of
+  view, or behind something else — instead of one message covering all of them.
+- The step budget counts work done, not attempts made; stale retries and second looks no longer
+  spend a leg's allowance, with a separate spin cap for loops making no progress.
+- Waiting is an operation the model can choose rather than a fixed pause, and the settle poll starts
+  impatient and backs off only when the page proves it is churning.
+- The page is watched while Jev is thinking rather than before the request, so proving it has gone
+  still is free: it fits inside a wait the step was making anyway. A rejected decision then has a
+  fresh read already in hand and costs one more request instead of a request and a read.
+- Fixed: the settle budget had never applied. The CLI always sent the key, so `fetch("steady", 0.2)`
+  returned the `nil` that was there, `nil.to_f` is zero, and the backoff after a stale retry was
+  multiplying that zero by two. No decision had waited for a page in months.
+- A rejected decision says which part of the guard moved — the document, the route, the viewport, a
+  field elsewhere, the target itself, or the content around it — instead of reporting that something,
+  somewhere, changed.
+- The route comparison drops the query string. Sites rewrite it constantly to hold state (a flights
+  form puts the itinerary in `?tfs=` and rewrites it on every keystroke), and comparing the full URL
+  rejected decisions about controls that had not moved. Removed that rejection reason entirely.
+- A fill is checked against its target like a click, instead of falling back to the whole-page
+  marker, which compares the title, every word of text and every action on the page.
+- On the flights form: **0.67 wall seconds per decision, against 1.04**; a rejected decision costs
+  428ms against 695ms; reading the page costs 38ms per decision against 120ms. The rejection rate
+  barely moved (27% to 25%) — what remains is the page genuinely changing, and re-deciding is the
+  right answer to that. Removing the retry backoff was tried and reverted: rejections went from 4.3
+  to 7.3 a run.
+- Unit tests for the three pieces that had only been covered through the loop: the action space, the
+  decider, and the MCP bridge. The bridge's run against a fake `safaridriver --mcp` speaking real
+  JSON-RPC over a real pipe, so a silent server, a dead one, and a document that took the installed
+  runtime with it are all exercised rather than described. Nine deliberate mutations — folding
+  actions by node, per-option select targets, the argmax and sum checks on a distribution, reading
+  an unnamed head, retrying a mutation whose runtime vanished — were each confirmed to fail a test.
+
+- Initial Safari backend: scoped windows, snapshot observations, guarded actions.
+- Interactive sessions: a background server holds one window behind a socket in `~/.wrangle`, so
+  `observe` and `act` are separate shell commands against the same page.
+- Every action reports what moved — appeared/gone controls, text and scroll deltas, and an explicit
+  "nothing changed" — so a caller can tell a click that worked from one that did not.
+- `--settle` polls until the page stops changing rather than sleeping a guessed interval, and
+  waits out a quiet floor first so a click that navigates is not mistaken for one that did nothing.
+- Distinct exit codes separate "observe and retry" from "this session is over".
+- `skills/wrangle`: an Agent Skill so an AI agent drives Safari by shell command, not by script.
+- Fixed the test fixture emitting `scroll` as an integer where Safari emits `{y, height}`.
+- Tests cover 98% of lines and 95% of branches, measured and enforced with Ruby's own `Coverage`
+  module — no coverage gem, since adding a dependency to check that Wrangle has none would undercut
+  the claim. Getting there found three real defects: a client that raised a raw `Errno::EPIPE` when a
+  session died mid-write instead of saying the session had gone, a `--version` flag that did not
+  exist despite the `version` subcommand doing, and a test suite that could reach the real Jev
+  endpoint and spend money whenever a test forgot to pass a fake.

data/LICENSE.txt

@@ -0,0 +1,48 @@
+MIT License
+
+Copyright (c) 2026 Eric Boehs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+---
+
+lib/wrangle/js/snapshot.js is vendored from browser-use/jev-ultrafast and is
+used under the MIT License:
+
+MIT License
+
+Copyright (c) 2026 Browser Use
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,473 @@
+# wrangle
+
+[![CI](https://github.com/ericboehs/wrangle/actions/workflows/ci.yml/badge.svg)](https://github.com/ericboehs/wrangle/actions/workflows/ci.yml)
+[![Gem Version](https://badge.fury.io/rb/wrangle.svg)](https://rubygems.org/gems/wrangle)
+
+**Hand one Safari window to a program, and no more than that.**
+
+Wrangle drives an ordinary Safari window through Apple Events. There is no automation session, no
+extension, and no native helper — so the window stays a real one you can see, keep, and take back at
+any moment. It is pure Ruby with **no runtime dependencies**: everything it needs ships with Ruby and
+macOS.
+
+The usual way to automate Safari is `safaridriver --enable`, which gives you a quarantined browser
+with a banner across the top, none of your cookies, and none of your sessions. That is the right tool
+for testing a site. It is the wrong tool for doing something *in* a browser you are already logged
+into. Wrangle is for the second case.
+
+```ruby
+require "wrangle"
+
+Wrangle::Safari.open("https://example.com", display: 1) do |session|
+  page = session.observe
+  link = page["actions"].find { |a| a["label"] == "Learn more" }
+  session.act(link, page)
+  puts session.observe["title"]   # => "Example Domains"
+end
+# the window Wrangle opened is closed here; a window you handed it never would be
+```
+
+## Install
+
+```ruby
+gem "wrangle"
+```
+
+Requires macOS, Safari, and Ruby 3.2+. You also need two things switched on once, by hand:
+
+- **Safari → Settings → Advanced → Allow JavaScript from Apple Events.**
+- The first run raises an Apple Events permission prompt. Approve it, or find it later under
+  **System Settings → Privacy & Security → Automation**.
+
+Wrangle will not change either setting for you.
+
+## Two ways in
+
+**A window Wrangle opens.** It owns this one, so it may close it.
+
+```ruby
+session = Wrangle::Safari.open("https://example.com", display: 1)
+session = Wrangle::Safari.open("https://example.com", bounds: [0, 0, 1200, 900])
+```
+
+**A window you hand over.** Already open, already signed in, already where you left it. Wrangle will
+never close it and never navigate it.
+
+```ruby
+Wrangle::Safari.windows(titles: true)
+# => [{"window_id"=>26081, "tabs"=>4, "display"=>0, "title"=>"Home / X", ...}]
+
+session = Wrangle::Safari.attach(window_id: 26081)
+```
+
+Titles and URLs identify a tab to whoever owns it, so `windows` omits them unless you ask.
+
+## Observing
+
+`observe` returns one snapshot of the scoped tab:
+
+```ruby
+page = session.observe
+
+page["url"]         # "https://example.com/"
+page["title"]       # "Example Domain"
+page["text"]        # visible text, capped at 6000 characters
+page["scroll"]      # {"y" => 0, "height" => 997}
+page["fingerprint"] # sha256 over url + text + actions + scroll
+page["actions"]
+# [{"id"=>"e1", "kind"=>"click", "node"=>1, "role"=>"link", "label"=>"Learn more",
+#   "rect"=>{"x"=>384, "y"=>227.2, "w"=>82, "h"=>18.8}, "value"=>""},
+#  {"id"=>"wait", "kind"=>"wait", "label"=>"Wait for the page to update"}]
+```
+
+The five action kinds are `click`, `fill`, `select`, `scroll`, and `wait`. A `select` is expanded into
+one candidate per option, so choosing an option means choosing an action rather than supplying a
+string the page never offered.
+
+## Acting
+
+```ruby
+session.act(action, page)                    # click, select, scroll, wait
+session.act(action, page, text: "Lisbon")    # fill
+session.fresh?(page, action)                 # check without mutating
+```
+
+`act` takes the action **and** the observation it came from. That pairing is the whole point: an
+action must be an exact candidate from a page that is still the page you saw.
+
+## What it refuses to do
+
+This is the interesting part. Wrangle fails closed, and every refusal below is a distinct exception
+rather than a return value you can forget to check.
+
+**It will not act on an action you made up.** An action must be an exact, unambiguous candidate from
+the observation you pass alongside it. Change one field — a node id, a value — and it raises
+`ArgumentError` without dispatching anything. If two candidates share an id, it refuses rather than
+picks. This is the boundary that keeps model output from becoming instructions: a decision may only
+name something the page was just seen to offer. Model output never becomes JavaScript, a selector, a
+coordinate, a key command, or an option value that was not observed.
+
+**It will not act on a page that moved.** Before every mutation, Wrangle re-checks the target: a
+`guard` for clicks and selects, a `marker` for fills and scrolls. If the page shifted between your
+observation and your decision, you get `StalePage` and nothing was dispatched. Observe again.
+
+**It will not lose track of which window it was given.** Scope is one window id, one tab position, one
+expected URL, and one document epoch. If the window you handed over gains a tab, or a different tab
+becomes current, or a handed-over tab replaces its document, you get `ScopeLost` — and the session is
+finished. It does not search for a replacement window, because the window it was given is the only
+window it was given. A window Wrangle opened *is* allowed to navigate; a window you lent it is not.
+
+**It will not retry a mutation to find out whether it landed.** Every action carries a nonce and the
+page records a phase against it. If the reply goes missing, Wrangle reads the nonce back and resolves
+what actually happened. It never repeats the action. If the outcome still cannot be established you
+get `DeliveryUnknown`, the session is poisoned, and — since it can no longer describe what it would be
+closing — it leaves the window open.
+
+**It will not close a window it did not open.** `attach` sessions never close anything. Even an owned
+window is left alone if it gained tabs in the meantime.
+
+**It will not start when window ids are ambiguous.** Window ids are only unique within one Safari
+process, and `safaridriver` is fond of leaving extra ones behind. More than one running Safari and
+Wrangle refuses to start, rather than address the wrong browser. Override with
+`allow_multiple_safari: true` if you know what you are doing.
+
+```ruby
+Wrangle::Error            # base
+├─ Wrangle::BridgeError   # the osascript bridge failed
+│  ├─ Wrangle::BridgeTimeout
+│  └─ Wrangle::BridgeCallError  # #code, #scope?
+├─ Wrangle::ScopeLost        # terminal: the window/tab/document is not the one you gave
+├─ Wrangle::DeliveryUnknown  # terminal: an action may or may not have landed
+└─ Wrangle::StalePage        # recoverable: observe again
+```
+
+## Speed
+
+Measured against a real Safari on an M-series Mac, median of five runs:
+
+| Step | Time |
+|---|---:|
+| Start the bridge, open a window, bind the document | 718 ms |
+| First observation | 34 ms |
+| Subsequent observation | 33 ms |
+| One action | 84 ms |
+| Close | 140 ms |
+
+So a decision loop costs about **117 ms per act-and-observe step**. For comparison, the same work over
+Safari's MCP server measured 9,059 ms to start and 1,327 ms per action — roughly 12× the startup and
+16× the per-action cost.
+
+The reason is that an Apple Event costs about **17 ms flat**, no matter how much data it carries, so
+the only optimisation that matters is sending fewer of them. A read costs two events (one scope guard,
+one evaluation) and a mutation costs four. The page scripts are shipped once at startup instead of
+~12 KB per call, unresolved specifiers are addressed rather than resolved, and nothing reads window
+bounds on the hot path.
+
+## CLI
+
+```
+$ wrangle windows --titles
+   26081  display 0    4 tabs  Home / X
+   33389  display 1    1 tab   Are we the Krell? - YouTube
+
+$ wrangle displays
+0  x=0       y=31      1440x2529
+1  x=-1920   y=351     1920x1080
+```
+
+## Interactive sessions
+
+A browser session is only useful if it survives between commands, and a shell gives you one process
+per command. `wrangle open` starts a background server holding one window behind a socket in
+`~/.wrangle`, so every later command drives the same page.
+
+```
+$ wrangle open "https://www.google.com/travel/flights?q=Flights+from+OKC+to+DEN" --display 1 --settle 8
+page    "Oklahoma City to Denver | Google Flights"  <https://...>
+state   54da85dcabb5  scroll 0/1623  1218 chars  72 actions
+   13  click   button    1 passenger, change number of passengers.
+
+$ wrangle act 13
+acted   click "1 passenger, change number of passengers."
+changed text -1139
+  appeared    "Add adult", "Add child aged 2 to 11", "Done", "Cancel"
+  gone        "Change ticket type. Round trip", "Where from? Oklahoma City OKC"
+    1  click   button    Add adult
+    5  click   button    Done
+
+$ wrangle act 1
+acted   click "Add adult"
+  appeared    "Remove adult"
+
+$ wrangle text --match 'adult'
+Prices include required taxes + fees for 2 adults.
+
+$ wrangle close
+```
+
+Every action answers the only question that matters next: **what moved?** `"Remove adult"` appearing
+is the proof the count went 1 → 2. When nothing moves, it says so outright — `changed nothing — the
+page is byte-identical` — instead of leaving you to diff two page dumps.
+
+The numbers are refs into the last observation and they shift after every action. Acting on a stale
+one is refused rather than mis-clicked. `--settle N` polls until the page stops changing instead of
+sleeping a guessed interval; without it you will read half-loaded pages and believe them.
+
+| Command | |
+|---|---|
+| `open <url>` / `attach <id>` | start a session; `--display N`, `--side left`, `--session NAME` |
+| `observe` | look; `--match RE`, `--all`, `--settle S` |
+| `act <ref>` | one action; `--text STR`, `--settle S` |
+| `run` | decide and act in a loop; `--goal`, `--plan`, `--execute` |
+| `text` | page text; `--match RE` |
+| `status` / `close` | |
+
+Exit codes: `0` ok, `2` usage, `3` stale (observe and retry), `4` the session is over, `5` no
+session. Add `--json` to any command for the raw reply.
+
+`--side left|right|top|bottom` parks the window on half a display, which is usually where you want
+an agent's browser: big enough to render a real page, out of the way of yours.
+
+## Letting it decide
+
+Stepping by hand costs a full model turn per click. Measured against a real agent driving this same
+form, each turn was **5–6 seconds** — roughly fifteen times the cost of the decision itself. `wrangle
+run` closes that loop in-process using [Jev](https://typesafe.ai), a typed-choice model that picks
+one of the actions Wrangle already observed.
+
+```bash
+wrangle run --goal "Set the origin to OKC and the destination to DEN" \
+  --literal 'where from=OKC' --literal 'where to=DEN' --execute
+```
+
+It never invents text. `--literal LABEL=VALUE` supplies it; a fill with no matching literal stops the
+run and asks. Nothing touches the page without `--execute`.
+
+### Plans
+
+One sub-goal per leg, advancing internally when a leg reports itself done:
+
+```bash
+wrangle run --execute --min-confidence 0.4 \
+  --literal 'where from=OKC' --literal 'where to=DEN' \
+  --plan "Set the origin to OKC and the destination to DEN, choosing from each autocomplete list." \
+  --plan "Open the Departure field, then click the day Monday, October 12, 2026." \
+  --plan "Click Thursday, October 15, 2026, then click Done to confirm the dates." \
+  --plan "Open the passenger selector, add a second adult, then click Done." \
+  --plan "Click Search." \
+  --expect 'taxes \+ fees for 2 adults'
+```
+
+```
+== 1. Set the origin to OKC and the destination to DEN, choosing from each autocomplete list.
+ 1. did   Where from?                              (89% sure/93% target, jev 364ms, step 483ms)
+      typed: "OKC"
+ 3. would The page moved while deciding; looked again (1)   (0% sure, step 415ms)
+ 4. did   Will Rogers International Airport (OKC)   (87% sure/92% target, jev 282ms, step 474ms)
+...
+proven  the page shows "taxes \+ fees for 2 adults"
+```
+
+That run filled the whole form through the site's own calendar and passenger UI in **29 steps and
+~14 seconds of one command**, where hand-stepping the same task took ten agent turns and 129
+seconds. Narrow legs beat one broad goal: a leg that names the next concrete step gets 90%+
+confidence, where a whole-task goal leaves the model weighing whether it is already finished.
+
+A leg that cannot finish ends the plan. Later legs assume the earlier ones happened, so guessing
+past a failure is how a run types a date into a passenger field.
+
+### When it stops
+
+| | |
+|---|---|
+| `did` | acted, with how sure it was and where the time went |
+| `would` | proposed only (no `--execute`) |
+| `ask` | handed back — below the confidence floor, or needs a literal |
+| `done` / `blocked` | the leg reported itself finished, or stuck |
+
+Below `--min-confidence` (default `0.5`) it looks again once — a page half-rendered when the model
+looked reads as ambiguity, and a second decision costs ~350ms against 5–6s for a handoff — then
+hands back rather than acting. This is load-bearing: an early build executed a **5%-confidence**
+target and typed the origin into Google's "Where else?" multi-city field.
+
+Stopping gets the floor too, but `DONE` and `BLOCKED` are not symmetric. Inside a plan an uncertain
+`DONE` is cheap to be wrong about — the next leg simply does the work — while an uncertain `BLOCKED`
+abandons every remaining leg. So both get a second look, `DONE` then passes, and `BLOCKED` must earn
+its handoff. A leg that has not acted yet goes further and confirms a `BLOCKED` however sure it is:
+it started the instant the last leg ended, so it is often reading a page that is still loading, and
+a half-loaded page does not read as ambiguous — it reads as definite, and reads surer on the second
+look.
+
+### Checking its own work
+
+`DONE` is the model reporting on its own work, chosen from the same look that proposed the actions,
+and it is optimistic. An Amazon plan reported success with the filter it had been asked for never
+applied; a flights leg finished a passenger dialog it had not finished.
+
+So every request carries a second question — *is this goal's outcome actually visible on the page?*
+— answered independently of the one choosing actions. It costs no extra round trip, because Jev
+evaluates the heads in parallel, and it has no action to gain by agreeing. A confident `no`
+overrules the claim and the leg carries on working:
+
+```
+ 3. would Said done, but the page does not show "In the left sidebar, click..." (76% sure)
+ 4. did   Apply 4 Stars & Up filter to narrow results          (98% sure/100% target)
+ 5. done  DONE                                                 (79% sure)
+```
+
+An unsure `no` is ignored — a verifier that is merely uncertain is noise, not evidence. And a
+dispute is worth more than the claim, not final: the verifier reads one snapshot, while the actor
+knows what it did. A leg that applied an Amazon filter was disputed at 80% five runs in a row,
+because the only proof on the page was a single link offering to remove the filter again.
+
+So a dispute is decisive only against a leg that has **not done anything** — the premature-`DONE`
+case it was built for, where there is no work to weigh against the page's reading. A leg that acted
+looks again, then is taken at its word with the doubt written into the transcript:
+
+```
+ 3. done  Done, but the page does not show "...the 4 Stars & Up filter" (79% sure)
+```
+
+A whole-task check at the end of a plan was tried and dropped: asked whether a filtered, sorted list
+had been achieved, it scored **lower on runs that succeeded than on runs that failed**. Absence is
+much harder to see than presence, and a check that cannot tell the two apart is worse than none.
+
+### Deciding and waiting at the same time
+
+A decision is made about a snapshot, and the page is free to move while the model is reading it. If
+it does, the guard refuses the action and the whole decision is thrown away. On Google Flights that
+was about a quarter of all decisions.
+
+The obvious answer is to wait for the page to go still *before* asking. That is what `STEADY_BUDGET`
+was for, and it had never once run: the CLI always sent the key, so `fetch("steady", 0.2)` returned
+the `nil` that was there and `nil.to_f` is zero. The backoff after a stale retry was multiplying
+that zero by two. Nothing had waited for a page in months.
+
+Restoring it would have cost roughly what it saved — proving a page is still takes two looks about
+200ms apart, and a decision only takes ~350ms. So the looks happen **underneath** the request
+instead. Jev is asked on one thread while the page is watched on another, and the watching stops at
+the first pair of reads that agree. A quiet page now costs nothing to confirm, and when a decision
+is rejected the fresh read is already in hand, so the retry is one request rather than a request and
+a read.
+
+That left the question of why decisions were being rejected at all, which the transcript could not
+answer because every rejection said the same thing. The guard now reports which of its parts moved:
+
+```
+ 4. RESTALE  The page moved while deciding; looked again   [The target is gone]
+ 7. RESTALE  The page moved while deciding; looked again   [The page's address changed]
+```
+
+The second one was the bug. The guard compared `location.href` byte for byte, and Google Flights
+puts the whole itinerary in a `?tfs=` parameter and rewrites it on every keystroke. Comparing the
+origin and path instead — a real navigation, not a query string — removed that reason entirely. A
+genuine route change still shows up, three times over: the path changes, or the document does, or
+the DOM is rebuilt and the element's own identity changes with it.
+
+A fill was also being checked against the whole-page marker, which compares the title, every word of
+text and every action on the page, so any price or banner arriving anywhere rejected a decision
+about a search box that had not moved. Anything aimed at an element is now checked against that
+element.
+
+Measured on the flights form, against the same task and page:
+
+| | before | after |
+|---|---|---|
+| wall seconds per decision | 1.04 | **0.67** |
+| cost of one rejected decision | 695ms | **428ms** |
+| reading the page, per decision | 120ms | **38ms** |
+| rejected decisions | 27% | 25% |
+
+The rejection *rate* barely moved, and that is the honest result: what remains is the page genuinely
+changing under the decision — an autocomplete list re-rendering, a calendar day growing a price —
+and re-deciding is the right response to both. What got cheaper is being wrong.
+
+One change was tried and reverted. With the watch in place the backoff after a stale retry looked
+redundant, since the page has been settling during the request anyway. Removing it took rejected
+decisions from 4.3 to 7.3 per run and the run got slower, so it stayed.
+
+What is left is mostly Jev itself: about 350ms a call, flat regardless of how much page it is sent,
+and a little over half of a run.
+
+### Backends
+
+`--backend jxa` (default) drives the running Safari through Apple Events. `--backend mcp` uses
+`safaridriver --mcp` instead: per-action latency drops from ~120ms to ~3ms, but it pays ~4s of
+startup, so it only amortises past roughly 28 actions. It is also **experimental** — its automation
+tab is backgrounded, and pages whose menus animate on `requestAnimationFrame` (Google's ticket-type
+selector, for one) never respond to a click that works fine under JXA.
+
+## Use it from an AI agent
+
+`skills/wrangle` is an [Agent Skill](https://agentskills.io) teaching the loop above, so an agent
+drives Safari with shell commands and never writes Ruby. For [pi](https://github.com/badlogic/pi):
+
+```bash
+pi package add git:github.com/ericboehs/wrangle
+```
+
+Or point any harness at `skills/wrangle/SKILL.md`.
+
+## How it works
+
+One `osascript -l JavaScript` process stays alive for the session and speaks newline-delimited JSON
+over a pipe. Spawning it costs ~56 ms; talking to one that already exists costs ~0.3 ms.
+
+Three pieces of JavaScript do the actual work. `bridge.js` runs in JXA and owns the Safari objects,
+scope checks, and window lifecycle. `page.js` and `snapshot.js` run in the page: one installs the
+document epoch and executes guarded actions, the other builds the observation.
+
+Page requests are JSON, passed as a **single argument** to a fixed function that was installed at
+startup:
+
+```js
+(pageScript)({"op":"act","action":{...},"nonce":"..."}, () => (snapshotScript))
+```
+
+Nothing a caller supplies is ever interpolated into the program's structure.
+
+One honest caveat: actions are dispatched as synthetic DOM events. They are not OS-level trusted
+input, and a page that checks `event.isTrusted` will know the difference.
+
+## Limitations
+
+- macOS and Safari only.
+- No navigation API — to visit a different URL, open another window.
+- No screenshots, no file uploads, no credential entry, no arbitrary JavaScript from the caller.
+- Only one Safari process may be running.
+- Observed page text is capped at 6000 characters; fill text at 2000.
+- Requires *Allow JavaScript from Apple Events*, which is a real privilege. Grant it deliberately.
+
+## Development
+
+No bundle, no compiler, no native extensions:
+
+```
+rake          # test + node --check on the JavaScript (+ rubocop if installed)
+rake test
+```
+
+RuboCop is optional and commented out of the `Gemfile`, because it wants a native `json` build and a
+checkout should not need a working compiler.
+
+The suite runs against a fake bridge subprocess that speaks the real protocol, so it exercises the
+transport, the scope rules, and all four delivery-resolution outcomes without touching a browser.
+Jev's client runs against a real HTTP server on a real socket for the same reason: everything worth
+checking there — a 429 that has to be retried, a connection that opens and then says nothing — is a
+property of the transport, not of a stub.
+
+```
+COVERAGE=1 rake test                      # per-file lines and branches
+COVERAGE=1 COVERAGE_DETAIL=1 rake test    # and which ones are missing
+```
+
+Coverage is measured with Ruby's own `Coverage` module rather than a gem: adding a dependency to
+check that Wrangle has none would be a strange way to keep the claim. CI enforces a floor of 95% on
+branches as well as lines, because line coverage says very little about a codebase whose main job is
+refusing things — a guard runs on every happy path and never once refuses.
+
+## License
+
+MIT. `lib/wrangle/js/snapshot.js` is vendored from
+[browser-use/jev-ultrafast](https://github.com/browser-use/jev-ultrafast) and used under the MIT
+License, Copyright (c) 2026 Browser Use. See [LICENSE.txt](LICENSE.txt).